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Notices 


Any reference to an IBM licensed program in this publication is not intended to state 
or imply that only IBM’s licensed program may be used. Any functionally equivalent 
product, program, or service that does not infringe any of IBM's intellectual property 
rights may be used instead of the IBM product, program, or service. Evaluation and 
verification of operation in conjunction with other products, except those expressly 
designated by IBM, is the user's responsibility. 

IBM may have patents or pending patent applications covering subject matter in this 
document. The furnishing of this document does not give you any license to these 
patents. You can send license inquiries, in writing, to the IBM Director of Licensing, 
IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 10594, USA. 

This publication contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


Programming Interface Information 

This book is intended to help you create programs using VisualAge C++ product. It 
primarily documents General-Use Programming Interface and Associated Guidance 
Information provided by VisualAge C++ product. 

General-Use programming interfaces allow the customer to write programs that obtain 
the services of VisualAge C++ compiler and debugger. 

However, this book also documents Diagnosis, Modification, and Tuning Information. 
Diagnosis, Modification, and Tuning Information is provided to help you debug your 
programs. 

Warning: Do not use this Diagnosis, Modification, and Tuning Information as a 
programming interface because it is subject to change. 

Diagnosis, Modification, and Tuning Information is identified where it occurs by an 
introductory statement to a chapter or section. 
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General Information 



About This Book 


The C language is a general-purpose, function-oriented programming language that 
you can use to create applications quickly and easily. C provides high-level control 
statements and data types similar to other structured programming languages as well 
as many of the benefits of a low-level language. Portable code is easily written in the 
C language. 

This book describes the library functions provided by the VisualAge C++ product, 
including those defined by: 

• The American National Standards Institute C Standard and International 
Standards Organization, ANSI/ISO 9899-1990[1992], and the amendment 
ISO/IEC 9899:1990/Amendment 1:1993(E) 

• The ISO/IEC 9945-1:1990/IEEE POSIX 1003.1-1990 standard 

• The X/Open Common Applications Environment Specification, System Interfaces 
and Headers, Issue 4 

• The IBM Systems Application Architecture (SAA) C Level 2 language definition. 

Unless explicitly indicated otherwise, all of the library functions described in this 
book are also available to C++ programs. 


Who Should Read This Book 

This book is written for application programmers who want to use the functions and 
macros provided by VisualAge C++ to develop and run C and C++ applications on 
the Operating System/2 (OS/2) platform. It assumes you have a working knowledge 
of the C programming language and the OS/2 operating system. 


Portability Considerations 

If you will be using VisualAge C++ to develop applications that will also be 
compiled and run on other systems, you should refer to the current language standards 
described in Chapter 1, “About This Book.” 

The language level is given for each function in Chapter 3, “Library Functions” on 
page 45. When creating programs to conform strictly to language standards such as 
ANSI/ISO or POSIX, do not use the functions described as extensions in this book. 
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Highlighting Conventions 

The following highlighting conventions are used in this book: 

Bol d Identifies commands and language keywords. 

Italics Identify parameters whose actual names or values are to be supplied by 
the programmer. 

Exampl e Identifies function names, examples of specific data values, examples 

of text similar to what you might see displayed, examples of portions 
of program code, messages from the system, or information that you 
should actually type. 


Icons Used in This Book 

The VisualAge C++ library uses icons to let you quickly scan pages for key concepts, 
examples, cross-references, and other information. 



This icon identifies examples that illustrate how to use a particular language feature 
or other concept presented in the book. 

This icon identifies cross-references to related information in this or other books. The 
icon may appear in the left margin where a number of cross-references are collected, 
or in miniature form within the text of a paragraph (like this: ) where only one or 

two cross-references are shown. 


How to Get Help 

There are three kinds of online information available to you while you are using 

VisualAge C++: 

Online documents 

These are complete documents, like the one you are reading now, 
presented online. These documents contain detailed information on the 
different aspects of VisualAge C++. For your convenience, the online 
documents are presented in two formats: 

• Standard format (.INF files). See “Getting Help Inside 

VisualAge C++” on page 3 for instructions on opening standard 
format documents from inside VisualAge C++. See “Getting Help 
from the Command Line” on page 4 for instructions on opening 
standard format documents from the command line. For a list of the 
VisualAge C++ documents that are available in standard format, see 
“Online Documents Available in VisualAge C++” on page 4. 
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• BookManager format (on CD-ROM only). See “BookManager 
Books” on page 4 for details on how to access online documents in 
this format. For a list of the VisualAge C++ documents that are 
available in BookManager format, see “The IBM VisualAge C++ 
BookManager Library” on page 865. 

Contextual help 

Contextual help is available throughout VisualAge C++. This help tells 
you all about the elements that you see in the interface, including menus, 
entry fields, and pushbuttons. 

How Do I help 

Many of the common tasks that you want to perform with 
VisualAge C++ are described in How Do I help. The How Do I help for 
a task gives you step-by-step instructions for completing the task. There 
is overall How Do I help for VisualAge C++, as well as individual task 
lists for each of its components. 

Getting Help Inside VisualAge C++ 

All three kinds of help are available directly within the VisualAge C++ interface: 

• To get general contextual help for the component of VisualAge C++ that you are 
using, press FI anywhere in the window. 

• To get contextual help on a particular menu, menu item, or button, highlight the 
element and press FI. 

• To get access to all of the help information that is available to you in a particular 
window, click on Hel p in the menu bar at the top of the window. This menu 
includes the following selections: 

- Hel p Index, an alphabetical list of all of the help topics that are available 
from this window 

- General Hel p, overall help for the window 

- Using Help, general information about the help facility 

- How Do I ..., the How Do I help for the component 

- Product Information, a dialog that shows the level of VisualAge C++ 
being used 

In addition, there are selections that let you open all of online documents that are 
available in VisualAge C++. 

• To get detailed information, open the Information folder in the VisualAge C++ 
folder. In this folder you will find icons for a variety of online documents that 
describe, in detail, the different aspects of VisualAge C++. To open a particular 
online document, double click on its icon. 
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Getting Help from the Command Line 

If you want, you can look at the online documents by issuing the view command. 

The installation routine stores the online document files in the \ I BMCPP\HELP directory. 
To view the Language Reference , for example, make C:\IBMCPP\HELP your current 
directory (substituting the drive where you installed VisualAge C++ for C:) and enter 
the following command: 

VIEW CPPLNG.INF 

If you want to get information on a specific topic, you can specify a word or a series 
of words after the file name. If the words appear in an entry in the table of contents 
or the index, the online document is opened to the associated section. For example, if 
you want to read the section on operator precedence in the Language Reference , you 
can enter the following command: 

VIEW CPPLNG.INF OPERATOR PRECEDENCE 

Getting Help for a Keyword or Construct 

If you are editing a file using Editor, you can get help for a keyword or construct by 
highlighting the word and pressing FI. In the other tools, you can get help for a 
keyword or construct by highlighting the word and pressing Ctrl -H. 

BookManager Books 

In addition to standard format, the online documents are also available in 
BookManager format in the CD-ROM version of VisualAge C++. You can read this 
information using either the IBM Library Reader/2 or IBM Library Reader/DOS. Lor 
details on installing and using the IBM Library Reader and BookManager books, see 
the README. ENG file in the root directory of the CD-ROM. 

Online Documents Available in VisualAge C++ 

The following documents are available in standard format: 


Building VisualAge C++ Parts 
for Fun and Profit 

Multimedia Subsystem 
Programming Guide 

SOM Programming 

Reference 

C Library Reference 

Open Class Libraiy 
Reference 

User's Guide 

Control Program Guide and 
Reference 

Open Class Libraiy User's 
Guide 

Visual Builder User's Guide 

Graphics Programming 

Guide and Reference 

OS/2 Bidirectional 
Language Support 
Development Guide 

Visual Builder Parts 

Reference 

IPF Guide and Reference 

OS/2 Tools Reference 

Editor Command Reference 

Kernel Debug Reference 

Presentation Manager 
Guide and Reference 

Welcome to VisualAge C++ 
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Language Reference Programming Guide Workplace Shell 

Programming Guide 

Multimedia Application REXX Reference Workplace Shell 

Programming Guide Programming Reference 

Multimedia Programming SOM Programming Guide 

Reference 


Changes to the C Library and this Document 

This section describes the changes made to the C runtime library for VisualAge C++ 
Version 3.0, and to this book, S25H-6964, from the previous version, S61G-1183. 

Changes to the C Library 

• The runtime library now supports locales and internationalization based on the 
IEEE POSIX P1003.2 and X/Open Portability Guide standards for global locales 
and coded character sets. 

• To support locales, including wide character sets, new functions, header files, and 
environment variables have been added. The functions include a number of 
multibyte functions defined in the 1993 proposed amendment to the ANSI/ISO C 
standard. 

• The memory management support has been completely redesigned to improve 
flexibility and performance. Enhancements include: 

- Functions for creating and using your own memory heaps. 

- Additional heap-checking functions. 

- Support for shared memory heaps. 

- A new environment variable, DDE4_HEAP_SKIP, that you can use to 
determine how often the heap is checked by debug memory management 
functions. 

- Debug versions of the tiled memory management functions. 

- Significantly reduced overhead per allocation from previous releases. 

Note: The new memory management design could surface memory problems in 
your applications that the previous version of C Set ++ did not catch. If 
exceptions or problems occur that did not occur with earlier versions: 

1. Rebuild your application to generate debug information and enable 
memory debugging (/Ti /Tm compiler options). 

2. Run your application and redirect stderr to a file (the memory 
debug messages are sent to stderr by default). 

3. Use the memory debug messages (and the debugger) to correct your 
memory problem. 
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Common problems are freeing an object twice, freeing an invalid object, 
writing to a freed object, or overwriting an allocated object beyond its 
requested size. 

You can simplify your debugging by using the debugger and setting appropriate 
breakpoints when the object is allocated, freed, or written to. You can also set a 
breakpoint on abort, which is called when a memory problem is detected. 

The Debugger also has a new feature you can use to automatically check all the 
memory heaps in your application each time your application stops running (for 
example, hits a breakpoint). See the User's Guide for more information about the 
Debugger. 

• Some VisualAge C++ extensions no longer begin with an underscore for 
compatibility with the X/Open standard: 


access 

execlp 

isatty 

stat 

chdi r 

execv 

1 f i nd 

swab 

chmod 

execve 

1 search 

tempnam 

close 

execvp 

1 seek 

tzset 

creat 

fdopen 

mkdi r 

umask 

dup 

fi1eno 

open 

uniink 

dup2 

fstat 

putenv 

utime 

execl 

getpid 

read 

wai t 

execle 

isascii 

rmdi r 

wri te 


To ensure compatibility with previous C Set ++ releases, VisualAge C++ maps 
the underscored name to the appropriate function name for you (for example, 
_access to access). 

• Functions to enable fast RAM semaphores have been added (_cxchg,_lxchg, 

and_sxchg). 

• The printf family of functions now prints (null) if you specify a null string for 
the %s or %ls format specifier. In previous releases, the printf functions 
produced no output for a null string. 

• The names of the runtime library files have changed. The new naming 
convention is: 

CPPpivvt 

where: 

p Is the platform or operating system. 

i Is the library identifier. 

vv Is the version number. 

t Is the type of library 
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The resulting library names are: 


Character Position 

Significance 

1 - 3 

4 

5 

6 - 

8 





7 



CPP 





Product prefix 


0 




OS/2 platform 



S 



Single-thread environment 



M 



Multithread environment 



N 



No runtime environment (subsystem) 




30 


Version number 3.0 





I 

Import library 





O 

Object library (contains initialization routines) 
Statically-bound library (no eighth letter) 


Changes to this Publication 

• The section on memory management functions has been expanded. 

• Information has been added for all new functions. 

• Information has been added for the DLL initialization and termination functions. 

• The order of chapters has been revised. 

• Minor technical and editorial changes have been made. 
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The C Library 


This chapter summarizes the available C library functions and indicates the page in 
this book where each is described. It also briefly describes what the function does. 
Each library function is listed according to the type of function it performs. 


Summary of Library Functions 
Error Handling 


Function 

Header 

File 

Page 

Description 

assert 

assert.h 

59 

Prints diagnostic messages. 

atexit 

stdlib.h 

62 

Registers a function to be executed at program termination. 

clearerr 

stdio.h 

94 

Resets error indicators. 

terror 

stdio.h 

223 

Tests the error indicator for a specified stream. 

jnatherr 

math.h 

405 

Processes errors generated by the functions in the math 
library. 

perror 

stdio.h 

459 

Prints an error message to stderr. 

raise 

signal .h 

480 

Initiates a signal. 

set crt msg handle 

stdio.h 

526 

Changes the file handle to which runtime messages are sent. 

signal 

signal .h 

540 

Allows handling of an interrupt signal from the operating 
system. 

strerror 

string.h 

579 

Sets pointer to system error message. 

_strerror 

string.h 

580 

Tests for system error. 

Process Control 

Function 

Header 

File 

Page 

Description 

_beginthread 

stdlib.h 
process. h 

71 

Creates a new thread. 

_cwait 

process.h 

131 

Delays the completion of a parent process until a child 
process ends. 

_disable 

builtin.h 

168 

Disables interrupts. 

_enable 

builtin.h 

194 

Enables interrupts. 

_endthread 

stdlib.h 
process.h 

195 

Terminates a thread. 

execl - _execvpe 

process.h 

200 

Load and run child processes. 

_exi t 

stdlib.h 
process.h 

205 

Ends the calling process without calling other functions. 

_freemod 

stdlib.h 

265 

Frees all references to a DLL for the calling process. 

getpid 

process, h 

308 

Gets the process identifier that identifies the calling process. 

_getTIBvalue 

builtin.h 

313 

Retrieves an unsigned long value from the Thread 
Information Block. 
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Function 

Header 

File 

Page 

Description 

_i nterrupt 

bui1tin. h 

346 

Calls an interrupt procedure. 

_1 oadmod 

stdlib.h 

376 

Loads a user-created DLL for the calling process. 

_onexit 

stdlib.h 

445 

Records the address of a function to call when the program 
ends. 

putenv 

stdlib.h 

471 

Adds new environment variables or modifies the values of 
those already existing. 

_searchenv 

stdlib.h 

523 

Searches a specified environment for a target file. 

_spawnl - _spawnvpe 

process.h 

548 

Start and run child processes. 

_threadstore 

stdlib.h 

665 

Accesses a thread-specific storage space. 

File and Directory 

Management 


Function 

Header 

File 

Page 

Description 

chdi r 

direct.h 

87 

Changes the current working directory to a specified 
directory. 

_chdrive 

direct.h 

89 

Changes the current working drive to a specified drive. 

fstat 

sys\stat.h 

281 

Gets and stores information about the open file. 

_ful1 path 

stdlib.h 

287 

Gets and stores the full path name of a given partial path. 

_getcwd 

direct.h 

300 

Gets the full path name of the current working directory. 

_getdcwd 

direct.h 

302 

Gets the full path name for the current directory of a 
specified drive. 

_getdrive 

direct.h 

304 

Returns an integer corresponding to the letter representing the 
current drive. 

_makepath 

stdlib.h 

401 

Creates a single path name. 

mkdi r 

direct.h 

436 

Creates a new directory. 

rmdi r 

direct.h 

499 

Deletes a directory. 

_splitpath 

stdl ib.h 

552 

Decomposes a path name into its four components. 

stat 

sys\stat.h 

561 

Stores information about a file or directory in a structure. 

Searching and Sorting 



Function 

Header 

File 

Page 

Description 

bsearch 

stdlib.h 
search.h 

76 

Performs a binary search of a sorted array. 

1 fi nd 

search.h 

374 

Performs a linear search for a value in an array. 

1 search 

search.h 

374 

Performs a linear search for a value in an array. 

qsort 

stdlib.h 
search.h 

478 

Performs a quick sort on an array of elements. 
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Regular Expressions 

Function Header 

File 

Page 

Description 

regcomp 

regex, h 

487 

Compiles a source regular expression into an executable 
version. 

regerror 

regex, h 

489 

Finds the description for the error code for a regular 
expression. 

regexec 

regex, h 

491 

Compares a string with a regular expression. 

regfree 

regex, h 

494 

Frees the memory for a regular expression, removing the 
compiled regular expression. 

Mathematical 

Function 

Header 

File 

Page 

Description 

abs 

stdlib.h 

48 

Calculates the absolute value of an integer. 

_cabs 

math.h 

78 

Calculates the absolute value of a complex number. 

ceil 

math.h 

84 

Calculates the double value representing the smallest integer 
that is greater than or equal to a number. 

di v 

stdlib.h 

169 

Calculates the quotient and remainder of an integer. 

erf 

math.h 

199 

Calculates the error function. 

erfc 

math.h 

199 

Calculates the error function for large numbers. 

exp 

math.h 

206 

Calculates an exponential function. 

fabs 

math.h 

207 

Calculates the absolute value of a floating-point number. 

fl oor 

math.h 

239 

Calculates the double value representing the largest integer 
that is less than or equal to a number. 

fmod 

math.h 

242 

Calculates the floating point remainder of one argument 
divided by another. 

frexp 

math.h 

270 

Separates a floating-point number into its mantissa and 
exponent. 

fsqrt 

math.h 

280 

Calculates the square root of a number. 

_fyl2x 

builtin.h 

290 

Calculates the base-2 logarithm of x and multiplies it by y. 

_fyl2xpl 

builtin.h 

291 

Calculates the base-2 logarithm of x+1 and multiplies it by y 

_f2xml 

builtin.h 

292 

Calculates ((2**x)-l). 

gamma 

math.h 

293 

Calculates the gamma function. 

hypot 

math.h 

333 

Calculates the hypotenuse. 

1 abs 

stdlib.h 

371 

Calculates the absolute value of a long integer. 

1 dexp 

math.h 

372 

Multiplies a floating-point number by an integral power of 2. 

1 di v 

stdlib.h 

373 

Calculates the quotient and remainder of a long integer. 

log 

math.h 

387 

Calculates natural logarithm. 

1 oglO 

math.h 

388 

Calculates base 10 logarithm. 

max 

stdlib.h 

408 

Compares two values and returns the larger of the two. 

mi n 

stdlib.h 

435 

Compares two values and returns the smaller of the two. 

modf 

math.h 

440 

Calculates the signed fractional portion of the argument. 

pow 

math.h 

460 

Calculates the value of an argument raised to a power. 

sqrt 

math.h 

556 

Calculates the square root of a number. 


Chapter 2. The C Library 11 



The C Library 


Trigonometric Functions 


Function 

Header 

File 

Page 

Description 

acos 

math.h 

51 

Calculates the arccosine. 

asi n 

math.h 

57 

Calculates the arc sine. 

atan 

math.h 

61 

Calculates the arctangent. 

atan2 

math.h 

61 

Calculates the arctangent. 

cos 

math.h 

111 

Calculates the cosine. 

cosh 

math.h 

112 

Calculates the hyperbolic cosine. 

_facos 

bui1tin.h 

math.h 

208 

Calculates the arccosine. 

_fasin 

bui1tin.h 

math.h 

210 

Calculates the arcsine. 

_fcos 

bui1tin.h 

math.h 

214 

Calculates the cosine. 

_fcossin 

bui1tin.h 

215 

Calculates the cosine and stores the sine. 

_fpatan 

bui1tin.h 

math.h 

246 

Calculates the arctangent. 

_fptan 

bui1tin.h 

math.h 

251 

Calculates the tangent. 

_fsi n 

bui1tin.h 

math.h 

277 

Calculates the sine. 

_fsincos 

bui1tin.h 

278 

Calculates the sine and stores the cosine. 

si n 

math.h 

543 

Calculates the sine. 

si nh 

math.h 

544 

Calculates the hyperbolic sine. 

tan 

math.h 

645 

Calculates the tangent. 

tanh 

math.h 

646 

Calculates the hyperbolic tangent. 

Bit Rotation 

Function 

Header 

File 

Page 

Description 

_crotl 

stdlib.h 
bui1tin.h 

117 

Rotates a character value to the left by a specified number of 
bits. 

_crotr 

stdlib.h 
bui1tin.h 

117 

Rotates a character value to the right by a specified number 
of bits. 

_1rotl 

stdlib.h 

392 

Rotates a long integer value to the left by a specified number 
of bits. 

_1rotr 

stdlib.h 

392 

Rotates a long integer value to the right by a specified 
number of bits. 

_rotl 

stdlib.h 
bui1tin.h 

514 

Rotates an integer value to the left by a specified number of 
bits. 

_rotr 

stdlib.h 

514 

Rotates an integer value to the right by a specified number of 
bits. 

_srotl 

stdlib.h 
bui1tin.h 

558 

Rotates a short integer value to the left by a specified number 
of bits. 

_srotr 

stdlib.h 
bui1tin.h 

558 

Rotates a short integer value to the right by a specified 
number of bits. 
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Bessel Functions 


Function 

Header 

File 

Page 

Description 

JO 

math.h 

74 

0 order differential equation of the first kind. 

J1 

math.h 

74 

1st order differential equation of the first kind. 

Jn 

math.h 

74 

nth order differential equation of the first kind. 

_y0 

math.h 

74 

0 order differential equation of the second kind. 

_yi 

math.h 

74 

1st order differential equation of the second kind. 

_yn 

math.h 

74 

nth order differential equation of the second kind. 

Fast RAM Semaphores 



Function 

Header 

File 

Page 

Description 

_cxchg 

builtin.h 

134 

Exchanges a character value with a previously stored value. 

_1xchg 

builtin.h 

397 

Exchanges a long integer value with a previously stored 
value. 

_sxchg 

builtin.h 

641 

Exchanges a short integer value with a previously stored 
value. 

Floating-Point Unit Control 



Function 

Header 

File 

Page 

Description 

_clear87 

float.h 

builtin.h 

95 

Gets the floating-point status word and clears it. 

_control87 

float.h 

builtin.h 

109 

Gets the current floating-point control word and sets it. 

_fpreset 

float.h 

247 

Resets the floating-point unit to the default state. 

_status87 

float.h 

builtin.h 

563 

Gets the current floating-point status word. 

Date, Time, and Monetary Manipulation 

Function 

Header 

File 

Page 

Description 

asctime 

time.h 

55 

Converts time stored as a structure to a character string in 
storage. 

clock 

time.h 

97 

Determines processor time. 

ctime 

time.h 

129 

Converts time stored as a long value to a character string. 

difftime 

time.h 

166 

Calculates the difference between two times. 

_ftime 

sys\timeb.h 

285 

Obtains the current time and stores it in a structure. 

gmtime 

time.h 

321 

Converts time to Coordinated Universal Time, structure. 

1ocaltime 

time.h 

385 

Converts time to local time. 

mktime 

time.h 

438 

Converts local time into calendar time. 

_strdate 

time.h 

577 

Stores the current date in a buffer. 

strfmon 

monetary.h 

582 

Converts a monetary value to a formatted string. 

strftime 

time.h 

586 

Converts time to a multibyte character string. 

strptime 

time.h 

605 

Converts time stored as a character string to a structure. 
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Function 

Header 

File 

Page 

Description 

_strtime 

time.h 

617 

Copies the current time into a buffer. 

time 

time.h 

666 

Returns the time in seconds. 

tzset 

time.h 

681 

Changes the time zone and daylight saving time zone values. 

utime 

sys\utime.h 

734 

Sets the modification time for a file. 

wcsftime 

wchar.h 

760 

Converts the time and date to a wide character string. 

Type Conversion 

Function 

Header 

File 

Page 

Description 

atof 

stdlib.h 

63 

Converts a character string to a floating-point value. 

atoi 

stdlib.h 

65 

Converts a character string to an integer. 

atol 

stdlib.h 

67 

Converts a character string to a long integer. 

_atold 

stdlib.h 

math.h 

69 

Converts a character string to a long double value. 

_ecvt 

stdlib.h 

192 

Converts a floating-point number to a character string. 

_fcvt 

stdlib.h 

217 

Converts a floating-point number to a character string, 
rounding according to the FORTRAN F format. 

_gcvt 

stdlib.h 

294 

Converts a floating-point value to a character string, rounding 
according to the FORTRAN F or FORTRAN E formats. 

_i toa 

stdlib.h 

368 

Converts the digits of an integer to a character string. 

_1 toa 

stdlib.h 

395 

Converts the digits of a long integer to a character string. 

strtod 

stdlib.h 

621 

Converts a character string to a double value. 

strtol 

stdlib.h 

625 

Converts a character string to a long integer. 

strtold 

stdlib.h 

627 

Converts a character string to a long double value. 

strtoul 

stdlib.h 

629 

Converts a string to an unsigned long integer. 

_ultoa 

stdlib.h 

716 

Converts the values of a long value to a character string. 

wcstod 

wchar.h 

778 

Converts a wide character string to a double value. 

wcstol 

wchar.h 

782 

Converts a wide character string to a long integer. 

wcstoul 

wchar.h 

786 

Converts a wide character string to an unsigned long integer. 

wctob 

wchar.h 

792 

Converts a wide character to a single-byte character. 

Multibyte and Wide-Character Type Conversion 

Function 

Header 

File 

Page 

Description 

mbrtowc 

wchar.h 

415 

Converts a multibyte character to a wide character (wchar_t); 
restartable version of mbtowc. 

mbsrtowcs 

wchar.h 

418 

Converts a multibyte character string to a wide character 
(wchar_t) string; restartable version of mbstowcs. 

mbstowcs 

stdlib.h 

420 

Converts a multibyte character string to a wide character 
(wchar_t) string. 

mbtowc 

stdlib.h 

422 

Converts a multibyte character to a wide character (wchar_t). 

wcrtomb 

wchar.h 

747 

Converts a wide character (wchar_t) to a multibyte character; 
restartable version of wctomb. 
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Function 

Header 

File 

Page 

Description 

wcsrtombs 

wchar.h 

774 

Converts a wide character (wchar_t) string to a multibyte 
character string; restartable version of wctomb. 

wcstombs 

stdlib.h 

784 

Converts a wide character (wchar_t) string to a multibyte 
character string. 

wctomb 

stdlib.h 

793 

Converts a wide character (wchar_t) to a multibyte character. 

Stream Input/Output 



Formatted Input/Output 



Function 

Header 

File 

Page 

Description 

fprintf 

stdio.h 

249 

Formats and prints characters to the output stream. 

fscanf 

stdio.h 

271 

Reads data from a stream into locations given by arguments. 

pri ntf 

stdio.h 

461 

Formats and prints characters to stdout. 

scanf 

stdio.h 

517 

Reads data from stdin into locations given by arguments. 

sprintf 

stdio.h 

554 

Formats and writes characters to a buffer. 

sscanf 

stdio.h 

559 

Reads data from a buffer into locations given by arguments. 

swprintf 

wchar.h 

635 

Formats and writes wide characters to a buffer. 

swscanf 

wchar.h 

637 

Reads wide characters from a buffer into locations given by 
arguments. 

vfprintf 

stdarg.h 

739 

Formats and prints characters to the output stream using a 


stdio.h 


variable number of arguments. 

vprintf 

stdarg.h 

741 

Formats and writes characters to stdout using a variable 


stdio.h 


number of arguments. 

vsprintf 

stdarg.h 

743 

Formats and writes characters to a buffer using a variable 


stdio.h 


number of arguments. 

vswprintf 

wchar.h 

745 

Formats and writes wide characters to a buffer using a 


stdarg.h 


variable number of arguments. 

Character and String Input/Output 



Function 

Header 

File 

Page 

Description 

fgetc 

stdio.h 

225 

Reads a character from a specified input stream. 

_fgetchar 

stdio.h 

227 

Reads a character from the standard input stream. 

fgets 

stdio.h 

230 

Reads a string from a specified input stream. 

fputc 

stdio.h 

252 

Prints a character to a specified output stream. 

_fputchar 

stdio.h 

254 

Prints a character to the standard output stream. 

fputs 

stdio.h 

255 

Prints a string to a specified output stream. 

getc 

stdio.h 

296 

Reads a character from a specified input stream. 

getchar 

stdio.h 

296 

Reads a character from stdin. 

gets 

stdio.h 

309 

Reads a line from stdin. 

putc 

stdio.h 

468 

Prints a character to a specified output stream. 
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Function 

Header 

File 

Page 

Description 

putchar 

stdio.h 

468 

Prints a character to stdout. 

puts 

stdio.h 

473 

Prints a string to stdout. 

ungetc 

stdio.h 

721 

Pushes a character back onto a specified input stream. 

Wide Character and String Input/Output 


Function 

Header 

File 

Page 

Description 

fgetwc 

stdio.h 

wchar.h 

232 

Reads a wide character from a specified input stream. 

fgetws 

stdio.h 

wchar.h 

232 

Reads a wide string from a specified input stream. 

fputwc 

stdio.h 

wchar.h 

257 

Writes a wide character to a specified output stream. 

fputws 

stdio.h 

wchar.h 

259 

Writes a wide character string to a specified output stream. 

getwc 

stdio.h 

wchar.h 

315 

Reads a wide character from a specified input stream. 

getwchar 

wchar.h 

317 

Reads a wide character from stdin. 

putwc 

stdio.h 

wchar.h 

474 

Writes a wide character to a specified output stream. 

putwchar 

wchar.h 

476 

Writes a wide character to stdout. 

ungetwc 

stdio.h 

wchar.h 

726 

Pushes a wide character back onto a specified input stream. 

Direct Input/Output 




Function 

Header 

File 

Page 

Description 

clearerr 

stdio.h 

94 

Resets error indicators. 

feof 

stdio.h 

222 

Tests end-of-file indicator for stream input. 

terror 

stdio.h 

223 

Tests the error indicator for a specified stream. 

tread 

stdio.h 

261 

Reads items from a specified input stream. 

fwrite 

stdio.h 

289 

Writes items to a specified output stream. 

File Positioning 




Function 

Header 

File 

Page 

Description 

fgetpos 

stdio.h 

228 

Gets the current position of the file pointer. 

fseek 

stdio.h 

273 

Moves the file pointer to a new location. 

fsetpos 

stdio.h 

275 

Moves the file pointer to a new location. 

ftell 

stdio.h 

283 

Gets the current position of the file pointer. 

1 seek 

io.h 

393 

Moves a file pointer to a new location. 

rewind 

stdio.h 

497 

Repositions the file pointer to the beginning of the file. 
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Function Header Page Description 

File 


fclose 

stdio.h 

212 

Closes a specified stream. 

_f cl oseal 1 

stdio.h 

213 

Closes all open streams, except the standard streams. 

fdopen 

stdio.h 

219 

Associates an input or output stream with a file. 

ffl ush 

stdio.h 

224 

Causes the system to write the contents of a buffer to a file. 

flushal1 

stdio.h 

240 

Writes the contents of buffers to files. 

fopen 

stdio.h 

243 

Opens a specified stream. 

freopen 

stdio.h 

268 

Closes a file and reassigns a stream. 

setbuf 

stdio.h 

524 

Allows control of buffering. 

setmode 

io.h 

535 

Sets the translation mode of a file. 

setvbuf 

stdio.h 

538 

Controls buffering and buffer size for a specified stream. 

File Operations 




Function 

Header 

File 

Page 

Description 

fi1eno 

stdio.h 

238 

Determines the file handle. 

remove 

stdio.h 

495 

Deletes a specified file. 

rename 

stdio.h 

496 

Renames a specified file. 

_rmtmp 

stdio.h 

513 

Closes and deletes temporary files. 

tempnam 

stdio.h 

657 

Creates a temporary file name in another directory. 

tmpfi1e 

stdio.h 

671 

Creates a temporary file and returns a pointer to that file. 

tmpnam 

stdio.h 

672 

Produces a temporary file name. 

uniink 

stdio.h 

729 

Deletes a file. 

Low-Level Input/Output 



Port Input/Output 




Function 

Header 

File 

Page 

Description 

_i np 

conio.h 

builtin.h 

340 

Reads a byte value from a specified input port. 

_i npd 

conio.h 

builtin.h 

342 

Reads a 4-byte value from a specified input port. 

_i npw 

conio.h 

builtin.h 

344 

Reads a 2-byte value from a specified input port. 

_outp 

conio.h 

builtin.h 

450 

Writes a byte value to a specified output port. 

_outpd 

conio.h 

builtin.h 

452 

Writes a 4-byte value to a specified output port. 

_outpw 

conio.h 

builtin.h 

454 

Writes a 2-byte value to a specified output port. 

umask 

io.h 

719 

Sets the file permission mask of the executing process 


environment. 

Character and String Input/Output 
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Function 

Header 

File 

Page 

Description 

_cgets 

conio.h 

85 

Reads a string from the keyboard into locations given by 
arguments. 

_cprintf 

conio.h 

113 

Formats and sends a series of characters and values to the 

screen. 

_cputs 

conio.h 

114 

Writes a string directly to the screen. 

_cscanf 

conio.h 

127 

Reads data from the keyboard into locations given by 
arguments. 

_getch 

conio.h 

298 

Reads a single character from the keyboard. 

_getche 

conio.h 

298 

Reads a single character from the keyboard and displays it. 

_kbhit 

conio.h 

369 

Tests if a key has been pressed on the keyboard. 

_putch 

conio.h 

470 

Writes a character to the screen. 

_ungetch 

conio.h 

723 

Pushes a character back to the keyboard. 

Direct Input/Output 

Function 

Header 

File 

Page 

Description 

read 

io.h 

482 

Reads bytes from a file into a buffer. 

wri te 

io.h 

799 

Writes bytes from a buffer into a file. 

File Positioning 

Function 

Header 

File 

Page 

Description 

_eof 

io.h 

197 

Determines whether the file pointer has reached the end of 
the file. 

tel 1 

io.h 

655 

Gets the current position of a file pointer. 
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Function 

Header 

File 

Page 

Description 

access 

io.h 

49 

Determines whether the given file exists and whether you can 
gain access to it. 

chmod 

io.h 

90 

Changes the permission setting of a file. 

close 

io.h 

99 

Closes a file associated with the handle. 

creat 

io.h 

115 

Creates a new file or opens and truncates an existing file. 

dup 

io.h 

186 

Associates a second file handle with an open file. 

dup2 

io.h 

189 

Associates a second file handle, with possibly different 
attributes, with an open file. 

isatty 

io.h 

352 

Determines whether the handle is associated with a character 

device. 

open 

io.h 

447 

Opens a file and prepares it for subsequent reading and 
writing. 

_sopen 

io.h 

545 

Opens a file and prepares it for subsequent shared reading or 
writing. 

File Operations 

Function 

Header 

File 

Page 

Description 

_chsize 

io.h 

92 

Lengthens or cuts off the file to a specified length. 

_filelength io.h 

Handling Argument Lists 

236 

Returns the length of a file. 

Function 

Header 

File 

Page 

Description 

va_arg 

stdarg.h 

737 

Allows access to variable number of function arguments. 

va_end 

stdarg.h 

737 

Allows access to variable number of function arguments. 

va_start 

stdarg.h 

737 

Allows access to variable number of function arguments. 

vfprintf 

stdarg.h 

stdio.h 

739 

Formats and prints characters to the output stream using a 
variable number of arguments. 

vprintf 

stdarg.h 

stdio.h 

741 

Formats and writes characters to stdout using a variable 
number of arguments. 

vsprintf 

stdarg.h 

stdio.h 

743 

Formats and writes characters to a buffer using a variable 
number of arguments. 

vswprintf 

wchar.h 

stdarg.h 

745 

Formats and writes wide characters to a buffer using a 
variable number of arguments. 
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Pseudorandom Numbers 


Function 

Header 

File 

Page 

Description 

rand stdlib.h 481 

srand stdlib.h 557 

Dynamic Memory Management 

Allocating and Freeing Memory 

Function Header Page 

File 

Returns a pseudorandom integer. 

Sets the starting point for pseudorandom numbers. 

Description 

_al 1 oca 

stdlib.h 
mal 1 oc .h 
bui 1 tin.h 

53 

Temporarily allocates storage space from the program's stack. 

cal 1 oc 

stdlib.h 
malloc .h 

80 

Reserves storage space for an array and initializes the values 
of all elements to 0. 

_debug_cal 1 oc 

stdlib.h 
mal 1 oc .h 

139 

Allocates memory and initializes it to 0, checks the heap, and 
stores information about the allocation. 

_debug_free 

stdlib.h 
mal 1 oc .h 

141 

Releases memory, checks the heap, and stores information 
about the operation. 

_debug_heapmin 

stdlib.h 
mal 1 oc .h 

143 

Returns unused memory in the heap to the operating system, 
and stores information about the operation. 

_debug_mal 1 oc 

stdlib.h 
mal 1 oc .h 

145 

Allocates memory and initializes it to OxAA, checks the heap, 
and stores information about the allocation. 

_debug_real 1 oc 

stdlib.h 
mal 1 oc .h 

147 

Changes the size of an allocated memory block, sets unused 
memory to OxAA, checks the heap, and stores information 
about the operation. 

_debug_tcal 1 oc 

stdlib.h 

mal 1 oc .h 

149 

Allocates tiled memory and initializes it to 0, checks the 
heap, and stores information about the allocation. 

_debug_tfree 

stdlib.h 

mal 1 oc .h 

151 

Releases tiled memory, checks the heap, and stores 
information about the operation. 

_debug_theapmi n 

stdlib.h 
mal 1 oc .h 

153 

Returns unused memory in the tiled heap to the operating 
system, and stores information about the operation. 

_debug_tmal 1 oc 

stdlib.h 

mal 1 oc .h 

155 

Allocates tiled memory and initializes it to OxAA, checks the 
heap, and stores information about the allocation. 

_debug_treal 1 oc 

stdlib.h 
mal 1 oc .h 

157 

Changes the size of an allocated tiled memory block, 
initializes unused memory to OxAA, checks the heap, and 
stores information about the operation. 

_debug_ucal 1 oc 

stdlib.h 
mal 1 oc .h 

160 

Allocates memory from a specified heap and initializes it to 

0, checks the heap, and stores information about the 
allocation. 

_debug_uheapmi n 

stdlib.h 
mal 1 oc .h 

162 

Returns unused memory from a specified heap to the 
operating system, and stores information about the operation. 

_debug_umal 1 oc 

stdlib.h 
mal 1 oc .h 

164 

Allocates memory from a specified heap and initializes it to 
OxAA, checks the heap, and stores information about the 
allocation. 
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Function 

Header 

File 

Page 

Description 

free 

stdlib.h 
malloc.h 

263 

Releases memory blocks. 

_heapmin 

stdlib.h 

mal1oc.h 

327 

Returns all unused memory from the runtime heap to the 
operating system. 

mal1oc 

stdlib.h 

mal1oc.h 

403 

Allocates memory blocks. 

real 1oc 

stdlib.h 

mal1oc.h 

484 

Changes storage size allocated for an object. 

_tcal1oc 

stdlib.h 

mal1oc.h 

647 

Allocates tiled memory and initializes it to 0. 

_tfree 

stdlib.h 

mal1oc.h 

659 

Releases tiled memory. 

_theapmin 

stdlib.h 

malloc.h 

663 

Returns all unused memory from the tiled runtime heap to the 
operating system. 

_tmal1oc 

stdlib.h 

malloc.h 

667 

Allocates a block of tiled memory. 

_treal1oc 

stdlib.h 

mal1oc.h 

679 

Changes the size of an allocated tiled memory block. 


Heap Information and Checking 


Function 

Header 

File 

Page 

Description 

_dump_al1ocated 

stdlib.h 

mal1oc.h 

180 

Writes information about currently allocated memory 
blocks. 

_dump_al1ocated_delta 

stdlib.h 

mal1oc.h 

183 

Writes information about currently allocated memory 
blocks since the last call for this information. 

_heap_check 

stdlib.h 

mal1oc.h 

323 

Validates all allocated memory blocks. 

_heapchk 

mal1oc.h 

325 

Validates all allocated and freed objects on the default 
heap. 

_heapset 

mal1oc.h 

328 

Validates all allocated and freed objects on the default 
heap, and sets all free memory to a specified value. 

_heap_walk 

mal1oc.h 

330 

Returns information about allocated and freed objects 
on the default heap. 

jnheap 

umal1oc.h 

433 

Finds out which heap an object was allocated from. 

_msize 

stdlib.h 

mal1oc.h 

441 

Returns the size of an allocated block. 

_tdump_al1ocated 

stdlib.h 

mal1oc.h 

649 

Writes information about currently allocated memory 
blocks from the tiled heap. 

_tdump_al1ocated_delta 

stdlib.h 

mal1oc.h 

652 

Writes information about currently allocated memory 
blocks from the tiled heap since the last call for this 
information. 

_theap_check 

stdlib.h 

mal1oc.h 

661 

Validates all allocated blocks of tiled memory. 

_udump_al1ocated 

umal1oc.h 

699 

Writes information about currently allocated memory 
blocks from a specified heap. 
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Function Header Page Description 

File 


_udump_al1ocated_ 

delta umal 

loc.h 

702 

Writes information about currently allocated memory 
blocks from a specified heap since the last call for this 
information. 

_uheap_check 

umal 

loc.h 

705 

Validates all allocated memory blocks from a specified 
heap. 

_uheapchk 

umal 

loc.h 

707 

Validates all allocated and freed objects on a specified 
heap. 

_uheapset 

umal 

loc.h 

711 

Validates all allocated and freed objects on a specified 
heap, and sets all free memory to a specified value. 

_uheap_walk 

umal 

loc.h 

713 

Returns information about allocated and freed objects 
on a specified heap. 

_ustats 

umal 

loc.h 

732 

Gets information about a specified heap. 

Heap Creation and Management 




Function 

Header 

File 

Page 


Description 

_uaddmem 

umalloc.h 

683 


Adds memory to a specified heap. 

_uclose 

umalloc.h 

688 


Closes a heap so it can no longer be used. 

_ucreate 

umalloc.h 

690 


Creates a heap of memory. 

_udefault 

umalloc.h 

694 


Changes the memory heap used as the default heap. 

_udestroy 

umal1oc.h 

696 


Destroys a heap. 

_uopen 

umalloc.h 

730 


Opens a heap so it can be used. 


22 


VisualAge C++ C Library Reference 




The C Library 


Memory Objects 


Function 

Header 

File 

Page 

Description 

memccpy 

string.h 
memory.h 

424 

Copies a buffer up to and including a specified character or 
number. 

memchr 

string.h 
memory.h 

425 

Searches a buffer for the first occurrence of a given 
character. 

memcmp 

string.h 
memory.h 

426 

Compares two buffers. 

memcpy 

string.h 
memory.h 

428 

Copies a buffer. 

memicmp 

string.h 
memory.h 

429 

Compares two buffers without regard to case. 

memmove 

string.h 
memory.h 

431 

Moves a buffer. 

memset 

string.h 
memory.h 

432 

Sets a buffer to a given value. 

swab stdlib.h 

Environment Interaction 

634 

Copies bytes from a specified source and swaps each pair of 
adjacent bytes. 

Function 

Header 

File 

Page 

Description 

abort 

stdlib.h 
process.h 

47 

Terminates a program abnormally. 

exi t 

stdlib.h 
process.h 

204 

Ends a program normally. 

getenv 

stdl ib.h 

305 

Searches environment variables for a specified variable. 

longjmp 

setjmp.h 

389 

Restores a stack environment. 

_parmdwords 

stdlib.h 
bailtin.h 

456 

Returns the hidden parameter passed in the AL register for 
functions with the _System calling convention. 

setjmp 

setjmp.h 

528 

Saves a stack environment. 

system stdlib.h 

process.h 

Setting and Querying Locale 

639 

Passes a string to the operating system's command interpreter. 

Function 

Header 

File 

Page 

Description 

csid 

stdlib.h 

126 

Determines the character set identifier for a character. 

getsyntx 

variant.h 

311 

Determines the encoding of special characters in the 
LC_SYNTAX locale category. 

i conv 

iconv.h 

334 

Converts characters from one codeset to another. 

iconv_close 

iconv.h 

337 

Deletes the conversion descriptor created by iconv open. 

iconv_open 

iconv.h 

338 

Creates a conversion descriptor for i conv to use in 
converting characters. 

1 ocaldtconv 

locale.h 

379 

Queries the date and time formatting conventions for the 


current locale. 
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Function 

Header 

File 

Page 

Description 

1 ocaleconv 

locale.h 

381 

Queries the numeric formatting conventions for the current 
locale. 

n1_1anginfo 

1 anginfo.h 
nl_types.h 

443 

Retrieves requested information for the current locale. 

setlocale 

locale.h 

530 

Changes or queries the locale. 

wcsi d 

stdlib.h 

762 

Determines the character set identifier for a wide character. 

wctype wchar.h 

String and Character Collating 

795 

Returns the handle for a character class or property. 

Function 

Header 

File 

Page 

Description 

cclass 

col 1 ate.h 

82 

Finds the list of collating elements for a given character 
class. 

col 1equiv 

col 1 ate.h 

101 

Finds the collating elements with the equivalent weighting as 
a specified character. 

col 1 order 

col 1 ate.h 

103 

Finds the number of collating elements in the collating order 
list. 

col 1 range 

col 1 ate.h 

105 

Finds the number of collating elements that fall between a 
range of weights. 

col 1tostr 

col 1 ate.h 

107 

Finds the corresponding string for a collating element. 

getmccol1 

col 1 ate.h 

306 

Finds the coll el _t representation for a collating element in a 
string. 

getwmccol 1 

col 1 ate.h 

wchar.h 

319 

Finds the coll el _t representation for a collating element in a 
wide string. 

ismccol1 el 

col 1 ate.h 

358 

Tests if a coll el _t value represents a multi-character 
collating element. 

maxcol1 

col 1 ate.h 

409 

Finds the largest value for a collating element. 

strcol1 

string.h 

571 

Compares two strings based on the collating elements in the 
current locale. 

strtocol1 

col 1 ate.h 

619 

Converts a string into a collating element (collel_t) value. 

wcscol1 

wchar.h 

754 

Compares two wide character strings based on the collating 
elements for the current locale. 

String Operations 

Function 

Header 

File 

Page 

Description 

strcat 

string.h 

565 

Concatenates two strings. 

strchr 

string.h 

566 

Locates the first occurrence of a specified character in a 
string. 

strcmp 

string.h 

567 

Compares the value of two strings. 

strcmpi 

string.h 

569 

Compares two strings without sensitivity to case. 

strcol1 

string.h 

571 

Compares two strings based on the collating elements for the 
current locale. 

strcpy 

string.h 

573 

Copies one string into another. 
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Function 

Header 

File 

Page 

Description 

strcspn 

string.h 

575 

Finds the length of the first substring in a string of characters 
not in a second string. 

strdup 

string.h 

578 

Reserves storage space for the copy of a string. 

stricmp 

string.h 

591 

Compares two strings without sensitivity to case. 

strl en 

string.h 

593 

Calculates the length of a string. 

strncat 

string.h 

595 

Adds a specified length of one string to another string. 

strncmp 

string.h 

597 

Compares two strings up to a specified length. 

strncpy 

string.h 

599 

Copies a specified length of one string into another. 

stmi cmp 

string.h 

601 

Compares two strings up to a specified length, without 
sensitivity to case. 

strnset 

string.h 

603 

Sets all characters in a specified length of string to a 
specified character. 

strpbrk 

string.h 

604 

Locates specified characters in a string. 

strrchr 

string.h 

610 

Locates the last occurrence of a character within a string. 

strrev 

string.h 

612 

Reverses the order of characters in a string. 

strset 

string.h 

603 

Sets all characters in a string to a specified character. 

strspn 

string.h 

614 

Locates the first character in a string that is not part of 
specified set of characters. 

strstr 

string.h 

616 

Locates the first occurrence of a string in another string. 

strtok 

string.h 

623 

Locates a specified token in a string. 

strxfrm 

string.h 

632 

Transforms strings according to locale. 

Character Testing 

Function 

Header 

File 

Page 

Description 

isalnum 

ctype.h 

347 

Tests for alphanumeric characters. 

isalpha 

ctype.h 

347 

Tests for alphabetic characters. 

isascii 

ctype.h 

350 

Tests if an integer is within the ASCII range. 

isblank 

ctype.h 

354 

Tests for the blank character attribute. 

iscntrl 

ctype.h 

347 

Tests for control characters. 

_iscsym 

ctype.h 

356 

Tests if a character is alphabetic or an underscore. 

_iscsymf 

ctype.h 

356 

Tests if a character is alphabetic, a digit, or an underscore. 

isdigit 

ctype.h 

347 

Tests for decimal digits. 

isgraph 

ctype.h 

347 

Tests for printable characters excluding the space. 

isiower 

ctype.h 

347 

Tests for lowercase letters. 

isprint 

ctype.h 

347 

Tests for printable characters including the space. 

ispunct 

ctype.h 

347 

Tests for printable characters excluding the space. 

isspace 

ctype.h 

347 

Tests for white-space characters. 

isupper 

ctype.h 

347 

Tests for uppercase letters. 

iswalnum 

wctype.h 

360 

Tests for alphanumeric wide characters. 

iswalpha 

wctype.h 

360 

Tests for alphabetic wide characters. 

iswblank 

wctype.h 

363 

Tests a wide character for the blank character attribute. 

iswctype 

wctype.h 

365 

Tests a wide character for a specified property. 

iswdigit 

wctype.h 

360 

Tests wide characters for decimal digits. 

iswgraph 

wctype.h 

360 

Tests for printable wide characters excluding the space. 
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Function 

Header 

File 

Page 

Description 

iswlower 

wctype.h 

360 

Tests wide characters for lowercase letters. 

iswprint 

wctype.h 

360 

Tests for printable wide characters including the space. 

iswpunct 

wctype.h 

360 

Tests for printable wide characters excluding the space. 

iswspace 

wctype.h 

360 

Tests for white-space wide characters. 

iswupper 

ctype.h 

360 

Tests wide characters for uppercase letters. 

isxdigit 

ctype.h 

347 

Tests for hexadecimal digits. 

iswxdigit 

wctype.h 

360 

Tests wide characters for hexadecimal digits. 

wcwidth 

wchar.h 

798 

Determines number of display positions required to display a 
given wide character. 

Character Case Mapping 



Function 

Header 

File 

Page 

Description 

strlwr 

string.h 

594 

Converts any uppercase letters in a string to lowercase. 

strupr 

string.h 

631 

Converts any lowercase letters in a string to uppercase. 

_toascii 

ctype.h 

676 

Converts a value to its ASCII character equivalent. 

tolower 

ctype.h 

676 

Converts a character to lowercase. 

_tolower 

ctype.h 

673 

Converts an uppercase ASCII character to lowercase. 

toupper 

ctype.h 

676 

Converts a character to uppercase. 

_toupper 

ctype.h 

673 

Converts a lowercase ASCII character to uppercase. 

towlower 

wctype.h 

677 

Converts a lowercase wide character to uppercase. 

towupper 

wctype.h 

677 

Converts a lowercase wide character to uppercase. 

Wide Character String Operation Functions 

Function 

Header 

File 

Page 

Description 

mbl en 

stdlib.h 

411 

Determines length of string. 

wcscat 

wcstr.h 

749 

Concatenates wchar_t strings. 

wcschr 

wcstr.h 

750 

Searches wchar_t string for character. 

wcscmp 

wcstr.h 

752 

Compares wchar_t strings. 

wcscol1 

wchar.h 

754 

Compares two wide character strings based on collating 
elements for the current locale. 

wcscpy 

wcstr.h 

756 

Copies wchar_t string. 

wcscspn 

wcstr.h 

758 

Searches wchar_t string for characters. 

wcslen 

wcstr.h 

763 

Finds length of wchar_t string. 

wcsncat 

wcstr.h 

764 

Concatenates wchar_t string segment. 

wcsncmp 

wcstr.h 

766 

Compares wchar_t string segments. 

wcsncpy 

wcstr.h 

768 

Copies wchar_t string segments. 

wcspbrk 

wcstr.h 

770 

Locates wchar_t characters in string. 

wcsspn 

wcstr.h 

776 

Finds number of wchar_t characters. 

wcsrchr 

wcstr.h 

772 

Locates wchar_t character in string. 

wcsstr 

wchar.h 

777 

Locates the first occurrence of a wide character string within 
another wide character string. 

wcstok 

wchar.h 

780 

Locates a specified token in a wide character string. 
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Function 

Header 

File 

Page 

Description 

wcswcs 

wcstr.h 

788 

Locates a wchar_t string in another wchar_t string. 

wcswi dth 

wchar.h 

789 

Determines the number of display positions required to 
display a given wide character string. 

wcsxfrm 

wchar.h 

790 

Transforms wide character strings according to the current 


locale. 


Intrinsic Functions 

The VisualAge C++ compiler inlines some functions instead of generating a function 
call for them. Some of these functions are always inlined; others are inlined only 
when you compile with the optimization option (/0 or /Oc) on. 

Functions that Are Inlined when Optimization Is On 

When optimization is on (/0+), VisualAge C++ compiler by default inlines (generates 
code instead of a function call) the following C library functions: 


abs 

1 abs 

memmove 

strchr 

strncat 

_clear87 

memchr 

memset 

strcmp 

strncmp 

_control87 

memcmp 

_status87 

strcpy 

strncpy 

fabs 

memcpy 

strcat 

strl en 

strrchr 


The compiler inlines these functions when you include the appropriate header file that 
contains the function prototype and the #define and #pragma statements for the 
function. 

You can override the inlining either by undefining the macro or by placing the name 
of the function in parentheses, thus disabling the processor substitution. The function 
then remains a function call, and is not replaced by the code. The size of your object 
module is reduced, but your application program runs more slowly. 

Note: The optimize-for-size compiler option (/Oc) also disables the inlining of 
intrinsic functions. 
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Functions that Are Always Inlined 

The following functions are built-in functions, meaning they do not have any backing 
library functions, and are always inlined: 


_al 1 oca 

_fasin 

fsqrt 

_i npw 

_outpw 

_crotl 

_fcos 

_fyl 2 x 

_interrupt 

_parmd' 

_crotr 

_fcossin 

_fyl 2 xpl 

_1 rotl 

_rotl 

_cxchg 

_fpatan 

_f 2 xml 

_ 1 rotr 

_rotr 

_disable 

_fptan 

_getTIBval ue 

_lxchg 

_srotl 

_enable 

_f si n 

_i np 

_outp 

_srotr 

_facos 

_fsincos 

_i npd 

_outpd 

_sxchg 


Do not parenthesize the names of these functions. 


The built-in functions are all defined in <builtin.h>, in addition to the standard 
header definitions. 


Differentiating between Memory Management Functions 

The memory management functions defined by ANSI are cal 1 oc, mal 1 oc, real 1 oc, 
and free. These regular functions allocate and free memory from the default runtime 
heap. (VisualAge C++ has added another function, _heapmi n, to return unused 
memory to the system.) VisualAge C++ also provides different versions of each of 
these functions as extensions to the ANSI definition. 

All the versions actually work the same way; they differ only in what heap they 
allocate from, and in whether they save information to help you debug memory 
problems. The memory allocated by all of these functions is suitably aligned for 
storing any type of object. 


The following table summarizes the different versions of memory management 
functions, using mal loc as an example of how the names of the functions change for 
each version. They are all described in greater detail after the table. 



Regular Version 

Debug Version 

Default Heap 

mal 1oc 

_debug_mal1oc 

User Heap 

_umal1oc 

_debug_umal 1 oc 

Tiled Heap (/Gt) 

_tmal1oc 

_debug_tmal 1 oc 


To use these extensions, you must set the language level to extended, either with the 
/Se compiler option or the #pragma langlvl (extended) directive. 
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Heap-Specific Functions 

Use the heap-specific versions to allocate and free memory from a user-created heap 
that you specify. (You can also explicitly use the runtime heap if you want.) Their 
names are prefixed by _u (for "user heaps"), for example, _umal 1 oc, and they are 
defined in <umal 1 oc. h>. 

The functions provided are: 

• _ucalloc 

• _umalloc 

• _uheapmin 

Notice there is no heap-specific version of real loc or free. Because they both 
always check what heap the memory was allocated from, you can always use the 
regular versions regardless of what heap the memory came from. 

For more information about creating your own heaps and using the heap-specific 
memory management functions, see Managing Memory with Multiple Heaps in the 
Programming Guide. 

Tiled Functions 

Use the tiled memory management functions to allocate and free memory from the 
runtime's tiled memory heap. If you have objects that can be accessed by 16-bit 
code, you should store them in tiled memory. Tiled memory does not cross 64K 
boundaries, as long as the object is smaller than 64K. Objects larger than 64K are 
aligned on 64K boundaries, but will also cross 64K boundaries. 

When you use the tiled memory compiler option, /Gt, all calls to the regular memory 
management functions are mapped to their tiled versions. You can also call the tiled 
versions explicitly. 

Note: If you parenthesize the calls to the regular memory management functions, 
they are not mapped to their tiled versions. 

The names of the tiled versions are prefixed by _t (for "tiled"), for example, 
_tmalloc, and they are defined in <malloc.h> and <stdlib.h>. 

The functions provided are: 

• _tcalloc 

• _tfree 

• _theapmin 

• _tmalloc 

• trealloc 
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You can also create your own heaps of tiled memory. Creating your own heaps is 
described in Managing Memory Using Multiple Heaps in the Programming Guide. 

For more information about sharing objects between 32-bit and 16-bit code, see 
Calling Between 32-Bit and 16-Bit Code in the Programming Guide. 

Debug Functions 

Use these functions to allocate and free memory from the default runtime heap, just 
as you would use the regular versions. They also provide information that you can 
use to debug memory problems. 

Note: The information provided by these functions is Diagnosis, Modification, and 
Tuning information only. It is not intended to be used as a programming 
interface. 

When you use the debug memory compiler option, /Tm, all calls to the regular 
memory management functions are mapped to their debug versions. You can also 
call the debug versions explicitly. 

Note: If you parenthesize the calls to the regular memory management functions, 
they are not mapped to their debug versions. 

We recommend you place a #pragma strings (readonly) directive at the top of 
each source file that will call debug functions, or in a common header file that each 
includes. This directive is not essential, but it ensures that the file name passed to the 
debug functions can't be overwritten, and that only one copy of the file name string is 
included in the object module. 

The names of the debug versions are prefixed by _debug_, for example, 

_debug_mal 1 oc, and they are defined in <malloc.h> and <stdlib.h>. 

The functions provided are: 

• _debug_calloc 

• _debug_free 

• _debug_heapmi n 

• _debug_mal 1 oc 

• _debug_real 1 oc 

In addition to their usual behavior, these functions also store information (file name 
and line number) about each call made to them. Each call also automatically checks 
the heap by calling _heap_check (described below). 
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Three additional debug memory management functions do not have regular 
counterparts: 

• _dump_all ocated 

Prints information to file handle 2 (the usual destination of stderr) about each 
memory block currently allocated by the debug functions. You can change the 
destination of the information with the _set_crt_msg_handl e function. 

• _dump_al1ocated_delta 

Prints information to file handle 2 about each memory block allocated by the 
debug functions since the last call to _dump_al located or 
_dump_al 1 ocated_del ta. Again, you can change the destination of the 
information with the _set_crt_msg_handl e function. 

• _heap_check 

Checks all memory blocks allocated or freed by the debug functions to make sure 
that no overwriting has occurred outside the bounds of allocated blocks or in a 
free memory block. 

The debug functions call _heap_check automatically; you can also call it explicitly. 
To use _dump_al 1 ocated and _dump_al 1 ocated_del ta, you must call them 
explicitly. 

In C Set ++ releases prior to VisualAge C++ Version 3.0, you could not mix debug 
and regular versions of the memory management functions. For example, you could 
not allocate memory with mal loc and free it with _debug_free. This restriction no 
longer applies; real loc and free (debug or otherwise) can now handle memory 
allocated by any other allocation function. 

Heap-Specific Debug Functions 

The heap-specific functions also have debug versions that work just like the regular 
debug versions. Use these functions to allocate and free memory from the 
user-created heap you specify, and also provide information that you can use to debug 
memory problems in your own heaps. 

Note: The information provided by these functions is Diagnosis, Modification, and 
Tuning information only. It is not intended to be used as a programming 
interface. 

You can call them explicitly, or you can use the debug memory compiler option, /Tm, 
to map calls to the heap-specific functions to their debug counterparts. 

Note: If you parenthesize the calls to the heap-specific memory management 
functions, they are not mapped to their debug versions. 
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The names of the heap-specific debug versions are prefixed by _debug_u, for example, 
_debug_umal 1 oc, and they are defined in <umalloc.h>. 

The functions provided are: 

• _debug_ucal1oc 

• _debug_uheapmin 

• _debug_umal1oc 

• _udump_al1ocated 

• _udump_al1ocated_delta 

• _uheap_check 

Notice there is no heap-specific debug version of real loc or free. Because they 
both always check what heap the memory was allocated from, you always use the 
regular debug versions (_debug_reall oc and _debug_free), regardless of what heap 
the memory came from. 

For more information about debugging memory problems in your own heaps, see 
“Debugging Your Heaps” in the Programming Guide. 

Tiled Debug Functions 

The tiled functions also have debug versions that work just like the regular and 
heap-specific debug versions. Use these functions to allocate and free memory from 
the tiled VisualAge C++ runtime heap. They also provide information that you can 
use to debug memory problems with the tiled heap. 

Note: The information provided by these functions is Diagnosis, Modification, and 
Tuning information only. It is not intended to be used as a programming 
interface. 

You can call them explicitly, or you can use the debug memory and tiled memory 
compiler options /Tm and / Gt, to map calls to the regular memory management 
functions to their tiled debug counterparts. 

Note: If you parenthesize the calls to the heap-specific memory management 
functions, they are not mapped to their debug versions. 

The names of the tiled debug versions are prefixed by _debug_t, for example, 
_debug_tmal 1 oc, and they are defined in <malloc.h> and <stdlib.h>. 
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The functions provided are: 

• _debug_tcal 1 oc 

• _debug_tfree 

• _debug_theapmin 

• _debug_tmal 1 oc 

• _debug_treal 1 oc 

• _tdump_all ocated 

• _tdump_al1ocated_delta 

• _theap_check 

For more information about debugging memory problems, see “Debugging Your 
Heaps” in the Programming Guide. 


Infinity and NaN Support 

VisualAge C++ compiler supports the use of infinity and NaN (not-a-number) values. 
Infinity is a value with an associated sign that is mathematically greater in magnitude 
than any binary floating-point number. A NaN is a value in floating-point 
computations that is not interpreted as a mathematical value, and that contains a mask 
state and a sequence of binary digits. 

The value of infinity can be computed from 1.0 / 0.0. The value of a NaN can be 
computed from 0.0 / 0.0. 

Depending on its bit pattern, a NaN can be either quiet (NaNQ) or signalling (NaNS), 
as defined in the ANSI/IEEE Standard for Binary Floating-Point Arithmetic 
(754-1982). A NaNQ is masked and never generates exceptions. A NaNS may be 
masked and may generate an exception, but does not necessarily do so. 

VisualAge C++ compiler supports only quiet NaN values; all NaN values discussed 
below refer to quiet NaNs. 
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NaN and infinity values are defined as macro constants in the <float.h> header file. 


The macros 

are: 

Macro 
_I NFINITY F 
_I NFINITY 
_I NFINITY L 

Description 

Infinity of type float 

Infinity of type doubl e 

Infinity of type 1 ong doubl e 

_INFF 

Same as _INFINITYF 

_INF 

Same as _INFINITY 

_I NFL 

Same as _INFINITYL 

JIANF 

_nan 

JIANL 

Quiet NaN of type f 1 oat 

Quiet NaN of type doubl e 

Quiet NaN of type 1 ong doubl e 


You can get the corresponding negative values by using the unary minus operator (for 
example, -_INF). 

Note: The value of 0.0 can also be positive or negative. For example, 1.0 / (-0.0) 
results in -_INF. 

Because these macros are actually references to constant variables, you cannot use 
them to initialize static variables. For example, the following statements are not 
allowed: 

static double infval = _INF; 
static float nanval = 1.0 + _NANF; 

Flowever, you can initialize static variables to the numeric values of infinity and NaN: 

static double infval = 1.0 / 0.0; 
static float nanval = 0.0 / 0.0; 

Note: Although positive and negative infinities are specific bit patterns, NaNs are 

not. A NaN value is not equal to itself or to any other value. For example, if 
you assign a NaN value to a variable x, you cannot check the value of x with 
the statement if (_NAN == x). Instead, use the statement if (x != x). 

All relational and equality expressions involving NaN values always evaluate 
to FALSE or zero (0), with the exception of not equal (!=), which always 
evaluates to TRUE or one (1). 

jj For information on the bit mapping and storage mapping of NaN and infinity 
values, see the User's Guide. 
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Infinity and NaN in Library Functions 

When the language level is set to extended (using the /Se option or the #pragma 
langlvl (extended) directive), which is the default, infinity and NaN values can be 
passed as arguments to the scanf and printf families of library functions, and to the 
string conversion and math functions. At other language levels, these functions work 
as described in this book. 

This section describes how the library functions handle the infinity and NaN values. 

scant Family The scanf family of functions includes the functions scanf, fscanf, sscanf, and 

swscanf. When reading in floating-point numbers, these functions convert the strings 
INFINITY, INF, and NAN (in upper-, lower-, or mixed case) to the corresponding 
floating-point value. The sign of the value is determined by the format specification. 

Given a string that consists of NAN, INF, or INFINITY, followed by other characters, the 
scanf functions read in only the NaN or infinity value, and consider the rest of the 
string to be a second input field. For example, Nancy would be scanned as two fields. 
Nan and cy. 

Note: In the case of a string that begins with INF, the functions check the fourth 
letter. If that letter is not I (in upper- or lowercase), INF is read and 
converted and the rest of the string is left for the next format specification. If 
the fourth letter is I, the functions continue to scan for the full INFINITY 
string. If the string is other than INFINITY, the entire string is discarded. 
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Example: In the following example, fscanf converts NaN and infinity strings to 
their numeric values. 


linclude <stdio.h> 

int main(void) 

{ 

int n, count; 
double dl, d2, d3; 

FILE *stream; 

stream = tmpfi1e(); 

fputs(" INFINITY NAn INF", stream); 

rewind(stream); 

n = fscanf(stream, "%1F%1f%lF%n", &dl, &d2, &d3, &count); 

if (n ! = EOF) 

{ 

printf("Number of fields converted = %d\n", n); 
printf("Number of characters read = %d\n", count); 
printf("Output = %f %F %F\n", dl, d2, d3); 

} 

return 0; 

/* The expected output is: 

Number of fields converted = 3 
Number of characters read = 17 
Output = infinity NAN INFINITY */ 


Figure 1. Example of f scant Using NaN and Infinity Values 


flip] For more information on the scanf, fscanf, sscanf, and swscanf functions, see 
the entries for each function in Chapter 3, “Library Functions” on page 45. 

printf Family The printf family of functions includes the functions printf, fprintf, sprintf, 
swprintf, vfprintf, vprintf, vsprintf, and vswprintf. These functions convert 
floating-point values of infinity and NaN to the strings "INFINITY" or "infinity" and 
"NAN" or "nan". 
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String 

Conversion 

Functions 


The case is determined by the format specification, as is the sign (positive or 
negative). When converting these values, the printf functions ignore the precision 
width given by the format specification. 

Example: In the following example, printf converts the NaN and infinity values 
and prints out the corresponding string. 


linclude <stdio.h> 
linclude <float.h> 

int main(void) 

{ 

double infval = -(_INF); 
float nanval = _NANF; 

printf("-_INF is the same as %-15.30f\n", infval); 
printf("_NANF is the same as %-15.30F\n", nanval); 

return 0; 

/* The expected output is: 

-_INF is the same as -infinity 
NANF is the same as NAN */ 


Figure 2. Example of printf Using NaN and Infinity Values 


/ri For more information on the printf, fprintf, sprintf, vfprintf, vprintf, 
and vsprintf functions, see the entries for each function in Chapter 3, “Library 
Functions” on page 45. 

The string conversion functions that support infinity and NaN representations 
include the functions atof, _atold, _ecvt, _fcvt, _gcvt, strtod, strtold, and 
wcstod. 

The atof, _atold, strtod, strtold, and wcstod functions accept the strings 
INFINITY, INF, and NAN (in upper-, lower-, or mixed case) as input, and convert these 
strings to the corresponding macro value defined in <float.h>. The _ecvt, _fcvt, 
and _gcvt functions convert infinity and NaN values to the strings INFINITY and NAN, 
respectively. 

Note: If a signalling NaN string is passed to a string conversion function, a quiet 
NaN value is returned, and no signal is raised. 
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Math 

Functions 


Example: The following example uses atof to convert the strings "naN" and "inf" 
to the corresponding macro value. 


#include <stdlib.h> 
linclude <stdio.h> 

int main(void) 

{ 

char *nanstr; 
char *infstr; 

nanstr = "naN"; 

printf( "Result of atof = %.10e\n", atof(nanstr) ); 
infstr = "inf"; 

printf( "Result of atof = %.10E\n", atof(infstr) ); 
return 0; 

/* The expected output is: 

Result of atof = nan 
Result of atof = INFINITY */ 


Figure 3. Example of atof Using NaN and Infinity Values 


4h For more information on the individual string conversion functions, refer to the 
entries for them in Chapter 3, “Library Functions” on page 45. 

Most math functions accept infinity, negative infinity, and NaN values as input. 

(/tfil For information on those functions that do not accept these values, see “Math 
Functions without Infinity and NaN Support” on page 41.) In general, a NaN value 
as input results in a NaN value as output, and infinity values as input usually result in 
infinity values. If the input value is outside the domain or range of the function, 
errno is set to EDOM or ERANGE, respectively. 

The following tables display the results of each math function when NaN or infinity 
values are input, and the associated errno value if one exists. The first table lists the 
functions that take only one argument; the second lists those that take two arguments. 

Note: In some cases, infinity is always a valid input value for the function 
regardless of the language level (for example, atan). These cases do not appear in 
these two tables. 
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Table 1 (Page 1 of 2). NaN and Infinity Values 

in Math Functions 


Function 

Input 

Result 

errno Value 

acos 

NaN 

NaN 


asi n 

infinity 

0 

EDOM 


-infinity 

0 

EDOM 

atari 

NaN 

NaN 


ceil 

NaN 

NaN 


fl oor 

infinity 

infinity 



-infinity 

-infinity 


COS 

NaN 

NaN 

EDOM 

tan 

infinity 

NaN 

ERANGE 


-infinity 

NaN 

ERANGE 

cosh 

NaN 

NaN 



infinity 

infinity 

ERANGE 


-infinity 

infinity 

ERANGE 

erf 

NaN 

NaN 

EDOM 


infinity 

1 



-infinity 

-1 


erfc 

NaN 

NaN 

EDOM 


infinity 

0 



-infinity 

2 


exp 

NaN 

NaN 



infinity 

infinity 

ERANGE 


-infinity 

0 

ERANGE 

fabs 

NaN 

NaN 



infinity 

infinity 



-infinity 

infinity 


frexp 

NaN 

NaN, 0 

EDOM 


infinity 

NaN, 0 

EDOM 


-infinity 

NaN, 0 

EDOM 

gamma 

NaN 

NaN 

EDOM 


infinity 

infinity 

ERANGE 


-infinity 

NaN 

EDOM 

log 

NaN 

NaN 


loglO 

infinity 

infinity 



0 

-infinity 

ERANGE 


<0 

NaN 

EDOM 

modf 

NaN 

NaN, NaN 

EDOM 


infinity 

NaN, infinity 

EDOM 


-infinity 

NaN, -infinity 

EDOM 
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Table 1 (Page 2 of 2). NaN and Infinity Values 

in Math Functions 


Function 

Input 

Result 

errno Value 

si n 

NaN 

NaN 

EDOM 


infinity 

NaN 

ERANGE 


-infinity 

NaN 

ERANGE 

si nh 

NaN 

NaN 

EDOM 


infinity 

infinity 

ERANGE 


-infinity 

-infinity 

ERANGE 

sqrt 

NaN 

NaN 



infinity 

infinity 



-infinity 

0 

EDOM 

tanh 

NaN 

NaN 

EDOM 


infinity 

1 



-infinity 

-1 
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The functions in the following table take two arguments. The results from NaN and 
infinity values vary depending on which argument they are passed as. 


Table 2. Infinity and NaN Values in Math Functions 


Function 

Argument 1 

Argument 2 

Result 

errno Value 

atan2 

NaN 

any number 

NaN 

EDOM 


any number 

NaN 

NaN 


fmod 

NaN 

any number 

NaN 

EDOM 


any number 

NaN 

NaN 

EDOM 


±infinity 

any number 

0 

EDOM 

ldexp 

infinity 

any number 

infinity 

ERANGE 


-infinity 

any number 

-infinity 

ERANGE 


NaN 

any number 

NaN 

EDOM 

pow 

±infinity 

0 

NaN 

EDOM 


infinity 

-infinity 

NaN 

EDOM 


-infinity 

±infinity 

NaN 

EDOM 


-infinity 

<-l 

NaN 

EDOM 


-infinity 

<1, >-l 

NaN 

EDOM 


-infinity 

>1 

NaN 

EDOM 


NaN 

any number 

NaN 

EDOM 


any number 

NaN 

NaN 

EDOM 


<0 

infinity 

NaN 

EDOM 


1 

±infinity 

NaN 

EDOM 


±infinity 

±1 

0 

ERANGE 


>0, <1 

infinity 

0 

ERANGE 


>0, <1 

-infinity 

infinity 

ERANGE 


Note: If a signalling NaN is passed to a math function, the behavior is undefined. 

Math 

Functions 
without 
Infinity and 
NaN Support 


Note: If you expect the return value of a math function to be infinity or NaN, you 
should use the functions that are supported for these values. The advantage in using 
the floating-point unit math functions is a reduction in the processing time and in the 
size of your executable file. 


The following floating-point unit functions are not supported for use with 
infinity or NaN values. In general, a NaN or infinity value as input for these 
functions results in an undefined value, an invalid operation exception, or both. 
These functions do not set errno. 

_facos _fasin _fcos _fcossin 

_fpatan _fptan _fsin _fsincos 

_fsqrt _fyl2x _fyl2xpl _f2xml 
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Using Low-Level I/O Functions 

The VisualAge C++ compiler supports both stream and low-level I/O. The primary 
difference between the two types of I/O is that low-level I/O leaves the responsibility 
of buffering and formatting up to you. 

In general, you should not mix input or output from low-level I/O with that from 
stream I/O. The only way to communicate between stream I/O and low-level I/O is 
by using the fdopen or fileno functions. 


The low-level I/O functions include: 


access 

dup2 

fstat 

_setmode 

chmod 

_eof 

isatty 

_sopen 

_chsize 

fdopen 

1 seek 

stat 

close 

_fi1 elength 

open 

tel 1 

creat 

fi1eno 

read 

umask 

dup 



wri te 


When you use the low-level I/O functions, you should be aware of the following: 

• A handle is a value that identifies a file. It is created by the system and used by 
low-level I/O functions. For VisualAge C++, the handle returned by low-level 
I/O functions like open (called the C_handle) is the same as that returned by 
DosOpen (called the API_handle). As a result, you can get a file handle using the 
low-level I/O functions, and then use it with OS/2 APIs. 

Portability Note: Other compilers may map the file handle so that the 
C_handle and API_handle are different. If you will be compiling your programs 
with other compilers, do not write code that depends on the file handles being the 
same. 

You can pass handles between library environments without restriction. If you 
acquire a handle other than by using the VisualAge C++ library functions open, 
creat, _sopen, or fi 1 eno, you must run _setmode for that handle before you 
use it with other VisualAge C++ library functions. 

• The default open-sharing mode is SH_DENYWR. Use _sopen to obtain other sharing 
modes. 

• Text mode deletes ' \r 1 characters on input and changes '\n' to '\r\n' on 
output. 

• In a multithread environment, you must ensure that two threads do not 
attempt to perform low-level I/O operations on the same file at the same 
time. You must make sure that one I/O process is completed before another 
begins. 
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If the file mode is text, the low-level I/O functions treat the character 1 xla 1 in 
the following ways: 

- If it is detected in a nonseekable file, 'xla' is treated as end-of-file. In a 
seekable file, it is treated as end-of-file only if it is the last character. 

- If a file is opened as text with either the 0_APPEND or 0_RDWR flags and 
'xla' is the last character of the file, the last character of the file is deleted. 


Chapter 2. The C Library 
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Library Functions 


The VisualAge C++ libraries are divided into two parts: 

• Standard libraries, which define the SAA features and the VisualAge C++ 
standard extensions to SAA 

• Subsystem libraries, which are a subset of the standard libraries, and are used for 
subsystem development. The functions in these libraries do not require a runtime 
environment. 


This section lists alphabetically and describes all the functions that VisualAge C++ 
product offers, including the extensions to the ANSI/ISO C definition. For 
information on the subsystem libraries and the functions in them, see the chapter 
called “Developing Subsystems” in the Programming Guide. 


Each function description includes the following subsections: 

Format 

The prototyped declaration of the function and the header file in which it is 
found. To include the declaration in your code, include the header file. 

Description 

A brief description of what the function does, what parameters it takes, and 
how to use the function. 


Language Level 

The C language standard that each function belongs to (some fall under more 

than one): 

ANSI ANSI/ISO 9899-1990[1992] C standard (commonly referred to as 
the ANSI C standard or ANSI/ISO C standard). 

ANSI 93 A subset of the ISO/IEC 9899:1990/Amendment 1:1993(E). 

POSIX ISO/IEC 9945-1:1990/IEEE POSIX 1003.1-1990 standard. 

XPG4 X/Open Common Applications Environment Specification, System 
Interfaces and Headers, Issue 4. 

SAA IBM Systems Application Architecture Common Programming 
Interface (SAA CPI) Level 2 definition. 

Extension Extensions to the conventional standards, often specific to 

VisualAge C++. (These include standard functions that have 
additional features under VisualAge C++.) 


© Copyright IBM Corp. 1992, 1995 


Note: To use the library extensions, you must set the language 
level to extended (with the #pragma langlvl (extended) 
directive or the /Se option); note that this is the default. 


45 






Library Functions 


Return Value 

The value returned from a successful call to the function and the error return 
value. 

Example 

A short example of how to use the function. From the online C Library 
Reference , you can use the IPF Copy to File choice from the Services 
pull-down to copy a function example to a separate file (called TEXT.TMP by 
default). You can then compile, link, and run the example, or use the example 
code in your own source files. 

Related Information 

A list of other functions that are similar to or related to the function, and of 
other topics that provide additional information that help you use the function. 
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abort — Stop a Program 

Format linclude <stdlib.h> 

void abort(void); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

abort causes an abnormal program termination and returns control to the host 
environment. It is similar to exit, except that abort does not flush buffers and close 
open files before ending the program. Calls to abort raise the SIGABRT signal. 

Return Value There is no return value. 

This example tests for successful opening of the file myfi 1 e.mjq. If an error occurs, 
an error message is printed and the program ends with a call to abort. 

#inc1ude <stdio.h> 

#include <stdlib.h> 

int main(void) 

1 

FILE *stream; 

if (NULL == (stream = fopen("myfile.mjq", "r"))) { 
perror("Could not open data file"); 
abort(); 

} 

return 0; 

/**************************************************************************** 

If myfile.mjq does'nt exist, the output should be: 

Could not open data file: The file cannot be found. 
****************************************************************************/ 
i 

• “exi t — End Program” on page 204 

• “_exit — End Process” on page 205 

• “signal — Handle Interrupt Signals” on page 540 

• “<stdlib.h>” on page 816 
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abs — Calculate Integer Absolute Value 

Format linclude <stdlib.h> 

int abs (int n); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

abs returns the absolute value of an integer argument n. 

Return Value There is no error return value. The result is undefined when the absolute value of 
the argument cannot be represented as an integer. The value of the minimum 
allowable integer is defined by -INT_MAX in the <limits.h> include file. 

This example calculates the absolute value of an integer x and assigns it to y. 

linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

int x = -4, y; 

y = abs (x); /* y = 4 */ 

printf("abs( %d ) = %d\n", x, y) ; 
return 0; 

/•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k 

The output should be: 
abs( -4 ) = 4 

} 

• “_cabs — Calculate Absolute Value of Complex Number” on page 78 

• “fabs — Calculate Floating-Point Absolute Value” on page 207 

• “labs — Calculate Absolute Value of Long Integer” on page 371 

• “<limits.h>” on page 806 

• “<stdlib.h>” on page 816 
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access 


access — Determine Access Mode 

Format linclude <io.h> 

int access(char * pathname , int mode); 

Description Language Level: POSIX, XPG4, Extension 

access determines whether the specified file exists and whether you can get access to 
it in the given mode. Possible values for the mode and their meaning in the access 
call are: 

Value Meaning 

06 Check for permission to read from and write to the file. 

04 Check for permission to read from the file. 

02 Check for permission to write to the file. 

00 Check only for the existence of the file. 

Note: In earlier releases of C Set ++, access began with an underscore (_access). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _access to access for you. 


Return Value access returns 0 if you can get access to the file in the specified mode. A return 

value of -1 shows that the file does not exist or is inaccessible in the given mode , and 
the system sets errno to one of the following values: 

Value Meaning 

EACCESS Access is denied; the permission setting of the file does not allow you to 
get access to the file in the specified mode. 

ENOENT The system cannot find the file or the path that you specified, or the file 
name was incorrect. 

EINVAL The mode specified was not valid. 

EOS2ERR The call to the operating system was not successful. 



This example checks for the existence of the file sample.dat. If the file does not 
exist, it is created. 
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#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

if (-1 == access("sample.dat", 00)) { 

printf("File sample.dat does not exist.\n"); 
printf("Creating sample.dat.\n"); 
system("echo Sample Program > sample.dat"); 
if (0 == access("sample.dat", 00)) 

printf("File sample.dat created.\n"); 


el se 

printf("File sample.dat exists.\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

File sample.dat does not exist. 

Creating sample.dat. 

File sample.dat created. 

****************************************************************************/ 

} 



“chmod — Change File Permission Setting” on page 90 
“_sopen — Open Shared File” on page 545 
“umask — Sets File Mask of Current Process” on page 719 
“<io.h>” on page 804 
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acos — Calculate Arccosine 

Format linclude <math.h> 

double acos(double x) ; 

Description Language Level: ANSI, SAA, POSIX, XPG4 

acos calculates the arccosine of x, expressed in radians, in the range 0 to n. 

Return Value acos returns the arccosine of x. The value of x must be between -1 and 1 

inclusive. If x is less than -1 or greater than 1, acos sets errno to EDOM and returns 0. 

This example prompts for a value for x. It prints an error message if x is greater than 
1 or less than -1; otherwise, it assigns the arccosine of x toy. 

#inc1ude <stdio.h> 

#inc1ude <stdlib.h> 

#include <math.h> 

Idefine MAX 1.0 

Idefine MIN -1.0 

int main(void) 

{ 

double x,y; 

printf("Enter x\n"); 
scanf("%lf", &x); 

/* Output error if not in range */ 
if (x > MAX) 

printf("Error: %1f too large for acos\n", x); 
el se 

if (x < MIN) 

printf("Error: %lf too small for acos\n", x); 
el se { 

y = acos(x); 

printf("acos( %lf ) = %lf\n", x, y); 

} 

return 0; 

/**************************************************************************** 

For the following input: 0.4 

The output should be: 

Enter x 

acos( 0.400000 ) = 1.159279 

****************************************************************************/ 

} 


• “asi n — Calculate Arcsine” on page 57 
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• “atari - atan2 — Calculate Arctangent” on page 61 

• “cos—Calculate Cosine” on page 111 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_facos — Calculate Arccosine” on page 208 

• “_fcos — Calculate Cosine” on page 214 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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alloca 


all oca — Temporarily Reserve Storage Block 

Format linclude <std1ib.h> /* also in <malloc.h> and <builtin.h> */ 

void *_al1oca(size_t size); 

Description Language Level: Extension 

_al1oca is a built-in function that temporarily allocates size bytes of storage space 
from the program's stack. The memory space is automatically freed when the 
function that called _al loca returns. 

Note: _al 1 oca is faster than other allocation functions such as mal 1 oc, but it has 
several limitations: 

• Because it is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library: 

- You cannot take the address of _al 1 oca. 

- You cannot parenthesize a call to _al loca. (Parentheses specify a call to the 
function's backing code, and _al loca has none). 

• Because _al loca automatically frees storage after the function that calls it 
returns, you cannot pass the pointer value returned by _al loca as an argument to 
the free function. 

• You cannot pass memory allocated by _al 1 oca to 16-bit programs, because it is 
never tiled. 

Because _al loca uses automatic storage, programs calling _al loca must not be 
compiled using the /Gs+ switch. This switch disables stack probes and does not 
guarantee that enough stack storage will be available. You should use the /Gs- 
switch, which is the default setting. 


Return Value _al 1 oca returns a pointer to the reserved space. If _al 1 oca cannot reserve the 
requested space, the program gets an out of stack exception. 



This example uses srand to generate five random numbers. The numbers determine 
how much space _al loca is to allocate for the array barstr. The result is a ragged 
two-dimensional array of strings. 
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#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include <time.h> 

int main(void) 

{ 

char *fullbar ="12345"; 
int range,rval; 
char *barstr[5]; 
i nt i; 

printf("Bar representation of 5 random numbers "); 
printf("(each generated from 1 to 5):\n\n"); 

/* set seed for rand function using time in seconds */ 

srand((unsigned int)time(NULL)); 

for (i =0; i <5; i++) { 

rval = (rand()+l)%5; /* generate random number from 0 to 4 */ 

/* for partial copy of fullbar, allocate space on stack for barstr 

from 2 to 10 characters long + one space for a null character */ 

barstr[i] = _al1oca((rval *sizeof(char) « 1)+3); 
memset(barstr[i], '\0', (rval *sizeof(char) « l)+3); 

/* copy random sized portion of fullbar */ 

strncpy(barstrfi], fullbar, ((rval + l)*2)); 

printf("%s\n", barstr[i]); /* print random length bar */ 

} 

return 0; 

/**-k , k-k-k‘k-k-k‘k-k-k-k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k-k 

The output should be similar to : 

Bar representation of 5 random numbers (each generated from 1 to 5): 

1 

12 3 4 
1 2 3 
1 2 3 4 5 
1 2 

i<‘k-k-k‘k-k-k‘k-k-k‘k-kic-k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k1c-k-k-k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k1<‘k-k-k-k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k/ 

} 



“cal loc — Reserve and Initialize Storage” on page 80 
“free — Release Storage Blocks” on page 263 
“mal loc — Reserve Storage Block” on page 403 
“real loc — Change Reserved Storage Block Size” on page 484 
/Gs option in the User's Guide 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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asctime — Convert Time to Character String 

Format linclude <time.h> 

char *asctime(const struct tm *time ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

The asctime function converts time, stored as a structure pointed to by time , to a 
character string. You can obtain the time value from a call to gmtime or localtime; 
either returns a pointer to a tm structure defined in <time.h>. See “gmtime — 
Convert Time” on page 321 for a description of the tm structure fields. 

The string result that asctime produces contains exactly 26 characters and has the 
format: 

"%.3s %.3s%3d %.2d:%.2d:%.2d %d\n" 

See “pri ntf — Print Formatted Characters” on page 461 for a description of format 
specifications. The following are examples of the string returned: 

Sat Jul 16 02:03:55 1994\n\0 
or 

Sat Jul 16 2:03:55 1994\n\0 

The asctime function uses a 24-hour-clock format. The days are abbreviated to: Sun, 
Mon, Tue, Wed, Thu, Fri, and Sat. The months are abbreviated to: Jan, Feb, Mar, Apr, 
May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. All fields have constant width. Dates with 
only one digit are preceded either with a zero or a blank space. The new-line 
character (\n) and the null character (\0) occupy the last two positions of the string. 

The time and date functions begin at 00:00:00 Universal Time, January 1, 1970. 

Return Value The asctime function returns a pointer to the resulting character string. There is no 
error return value. 

Note: asctime, ctime, and other time functions may use a common, statically 

allocated buffer to hold the return string. Each call to one of these functions 
may destroy the result of the previous call. 

This example polls the system clock and prints a message giving the current time. 
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#include <time.h> 
#include <stdio.h> 


int main(void) 

{ 

struct tm *newtime; 
time_t ltime; 

/* Get the time in seconds */ 
time(&ltime); 

/* Convert it to the structure tm */ 
newtime = localtime(&ltime); 

/* Print the local time as a string */ 

printf("The current date and time are %s", asctime(newtime)); 
return 0; 

/**************************************************************************** 

The output should be similar to : 


The current date and time are Fri Jun 28 13:51 1994 


ye***********************************'*'*'*'*'*'*'*'*'**'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'*'**'*'*'*'*'*'* 

} 


/ 



“ctime — Convert Time to Character String” on page 129 
“gmtime — Convert Time” on page 321 
“localtime — Convert Time” on page 385 
“mktime — Convert Local Time” on page 438 
“strftime — Convert to Formatted Time” on page 586 
“t i me — Determine Current Time” on page 666 
“printf — Print Formatted Characters” on page 461 
“<time.h>” on page 819 
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as in — Calculate Arcsine 

Format linclude <math.h> 

double asin(double x); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

asin calculates the arcsine of x, in the range -it/2 to jt/2 radians. 

Return Value asin returns the arcsine of x. The value of x must be between -1 and 1. If x is 
less than -1 or greater than 1, asin sets errno to EDOM, and returns a value of 0. 

This example prompts for a value for x. It prints an error message if x is greater than 
1 or less than -1; otherwise, it assigns the arcsine of x to y. 

#inc1ude <stdio.h> 

#inc1ude <stdlib.h> 

#include <math.h> 

Idefine MAX 1.0 

Idefine MIN -1.0 

int main(void) 

{ 

double x,y; 

printf("Enter x\n"); 
scanf("%lf", &x); 

/* Output error if not in range */ 

if (x > MAX) 

printf("Error: %1f too large for asin\n", x); 
el se 

if (x < MIN) 

printf("Error: %lf too small for asin\n", x); 
el se { 

y = asin(x); 

printf ("asin( %lf ) = %lf\n", x, y); 

} 

return 0; 

/**************************************************************************** 

For the following input: 0.2 

The output should be: 

Enter x 

asin( 0.200000 ) = 0.201358 

****************************************************************************/ 

} 




“acos — Calculate Arccosine” on page 51 


Chapter 3. Library Functions 57 



• “atari - atan2 — Calculate Arctangent” on page 61 

• “cos—Calculate Cosine” on page 111 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_fasin — Calculate Arcsine” on page 210 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsi n — Calculate Sine” on page 277 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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assert — Verify Condition 

Format linclude <assert.h> 

void assert(int expression ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

assert prints a diagnostic message to stderr and aborts the program if expression 
is false (zero). The diagnostic message has the format: 

Assertion failed: expression, file filename, line line-number. 
assert takes no action if the expression is true (nonzero). 

Use assert to identify program logic errors. Choose an expression that holds true 
only if the program is operating as you intend. After you have debugged the 
program, you can use the special no-debug identifier NDEBUG to remove the assert 
calls from the program. If you define NDEBUG to any value with a fdefine directive, 
the C preprocessor expands all assert invocations to void expressions. If you use 
NDEBUG, you must define it before you include <assert.h> in the program. 


Return Value There is no return value. 

Note: assert is implemented as a macro. Do not use the #undef directive with 
assert. 



In this example, assert tests string for a null string and an empty string, and 
verifies that length is positive before processing these arguments. 


Chapter 3. Library Functions 59 



assert 


#include <stdio.h> 

#include <assert.h> 

void analyze(char *string,int length) 

{ 

assert(string != NULL); /* cannot be NULL */ 

assert(*string != '\0'); /* cannot be empty */ 

assert(length >0); /* must be positive */ 

return; 

} 


int main(void) 

{ 

char *string = "ABC"; 
int length = 3; 

analyze(string, length); 

printf("The string %s is not null or empty, and has length %d \n", string, 

1ength); 
return 0; 

/•k-k-k-k-k-k-k-k-kle-k-k'R-k-k'k-k-k-k-k-kle-k-kle-k-k-k-k-k-k-k-k'k-k-k'R-k-k-k-k-k-k-k-k-k-k-kle-k-k-k-k-k-k-k-k'R-k-k'R-kicR-k-k-k-k-k-k-k-k-k-k-k-k 

The output should be: 

The string ABC is not null or empty, and has length 3 

1<‘k-k1<‘k'k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k'k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k-k-k-k‘k-k-k‘k-k-k/ 

} 



“abort — Stop a Program” on page 47 
“<assert.h>” on page 801 
#defi ne in the Language Reference 
#undef in the Language Reference 
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atan - atan2 — Calculate Arctangent 

Format linclude <math.h> 

double atan(double x); 

double atan2(double y, double x ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

atan and atan2 calculate the arctangent of x and y/x, respectively. 

Return Value atan returns a value in the range -it/2 to it/2 radians. atan2 returns a value in the 

range -jt to jt radians. If both arguments of atan2 are zero, the function sets errno to 
EDOM, and returns a value of 0. 

This example calculates arctangents using the atan and atan2 functions. 

#include <math.h> 

int main(void) 

{ 

double a,b,c,d; 

c = 0.45; 
d = 0.23; 
a = atan(c); 
b = atan2 (c, d); 

printf("atan( %lf ) = %lf\n", c, a); 
printf ("atan2( %lf, %lf ) = %lf\n", c, d, b); 
return 0; 

/**************************************************************************** 

The output should be: 

atan( 0.450000 ) = 0.422854 
atan2( 0.450000, 0.230000 ) = 1.098299 

****************************************************************************/ 

} 

• “acos — Calculate Arccosine” on page 51 

• “asi n — Calculate Arcsine” on page 57 

• “cos — Calculate Cosine” on page 111 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_fpatan — Calculate Arctangent” on page 246 

• “_fptan — Calculate Tangent” on page 251 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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atexit — Record Program Termination Function 

Format linclude <stdlib.h> 

int atexit(void [*func) (void)) ; 

Description Language Level: ANSI, SAA, POSIX, XPG4 

atexit records a function, pointed to by func, that the system calls at normal 
program termination. For portability, you should use atexi t to register up to 32 
functions only. The functions are executed in a last-in, first-out order. 

Return Value atexit returns 0 if it is successful, and nonzero if it fails. 

This example uses atexit to call the function goodbye at program termination. 

linclude <stdlib.h> 
linclude <stdio.h> 

void goodbye(void) 

{ 

/* This function is called at normal program termination */ 

printf("The function goodbye was called at program termination\n"); 

} 

int main(void) 

{ 

int rc; 

rc = atexit(goodbye): 
if (rc ! = 0) 

perror("Error in atexit"); 
return 0; 

/•k-k-k-k-k-klt-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-kie-k-k-k-k-k'k-k-k-k-k-kie-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-klck-k-k-k-kick-k-k-k-klckick 

The output should be: 

The function goodbye was called at program termination 

i 

• “exit — End Program” on page 204 

• “_exi t — End Process” on page 205 

• “_onexit — Record Termination Function” on page 445 

• “signal — Handle Interrupt Signals” on page 540 

• “<stdlib.h>” on page 816 




62 VisualAge C++ C Library Reference 




atof 


atof — Convert Character String to Float 

Format linclude <stdlib.h> 

double atof(const char *string ); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

atof converts a character string to a double-precision floating-point value. 

The input string is a sequence of characters that can be interpreted as a numerical 
value of the specified return type. The function stops reading the input string at the 
first character that it cannot recognize as part of a number; this character can be the 
null character that ends the string. 

atof expects a string in the following form: 



The white space consists of the same characters for which the isspace function is 
true, such as spaces and tabs, atof ignores leading white-space characters. 

For atof, digits is one or more decimal digits; if no digits appear before the 
decimal point, at least one digit must appear after the decimal point. The decimal 
digits can precede an exponent, introduced by the letter e or E. The exponent is a 
decimal integer, which may be signed. 

atof will not fail if a character other than a digit follows an E or if e is read in as an 
exponent. For example, 100elf will be converted to the floating-point value 100.0. 
The accuracy is up to 17 significant character digits. The string can also be 
"infinity", "inf", or "nan". These strings are case insensitive, and can be preceded 
by a unary minus (-). They are converted to infinity and NaN values. 

Return Value atof returns a double value produced by interpreting the input characters as a 

number. The return value is 0 if the function cannot convert the input to a value of 
that type. The return value is undefined in case of overflow. 
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This example shows how to convert numbers stored as strings to numerical values 
using the atof function. 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

double x; 
char *s; 



s = " -2309.12E-15"; 

x = atof(s); /* x = -2309.12E-15 */ 

printf("atof( %s ) = %G\n", s, x); 
return 0; 

/**************************************************************************** 

The output should be: 

atof( -2309.12E-15 ) = -2.30912E-12 

****************************************************************************/ 

} 

• “atoi — Convert Character String to Integer” on page 65 

• “atol — Convert Character String to Long Integer” on page 67 

• “_atold — Convert Character String to Long Double” on page 69 

• “strtod — Convert Character String to Double” on page 621 

• “strtol — Convert Character String to Long Integer” on page 625 

• “strtol d — Convert String to Long Double” on page 627 

• “Infinity and NaN Support” on page 33 

• “<stdlib.h>” on page 816 
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atoi — Convert Character String to Integer 

Format linclude <stdlib.h> 

int atoi(const char *string); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

atoi converts a character string to an integer value. 

The input string is a sequence of characters that can be interpreted as a numerical 
value of the specified return type. The function stops reading the input string at the 
first character that it cannot recognize as part of a number; this character can be the 
null character that ends the string. 

atoi does not recognize decimal points nor exponents. The string argument for this 
function has the form: 


A A ~ ,* 

whitespace-^ 

£ 

U Ly L LO ^ ^ 


where whitespace consists of the same characters for which the isspace function is 
true, such as spaces and tabs, atoi ignores leading white-space characters, digits 
is one or more decimal digits. 


Return Value atoi returns an int value produced by interpreting the input characters as a number. 

The return value is 0 if the function cannot convert the input to a value of that type. 
The return value is undefined in the case of an overflow. 



This example shows how to convert numbers stored as strings to numerical values 
using the atoi function. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 

{ 

i nt i; 
char *s; 

s = " -9885"; 

i = atoi(s); /* i = -9885 */ 

printf("atoi( %s ) = %d\n", s, i); 
return 0; 


/**************************************************************************** 

The output should be: 


atoi( -9885 ) = -9885 

****************************************************************************/ 



“atof — Convert Character String to Float” on page 63 
“atoi — Convert Character String to Long Integer” on page 67 
“_atold — Convert Character String to Long Double” on page 69 

“strtod — Convert Character String to Double” on page 621 

“strtol — Convert Character String to Long Integer” on page 625 

“strtold — Convert String to Long Double” on page 627 
“<stdlib.h>” on page 816 
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atol — Convert Character String to Long Integer 

Format linclude <stdlib.h> 

long int atol(const char *string ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

atol converts a character string to a long value. 

The input string is a sequence of characters that can be interpreted as a numerical 
value of the specified return type. The function stops reading the input string at the 
first character that it cannot recognize as part of a number; this character can be the 
null character that ends the string. 

atol does not recognize decimal points nor exponents. The string argument for this 
function has the form: 


A A ~ ,* 

whitespace-^ 

£ 

U Ly L LO ^ ^ 


where whitespace consists of the same characters for which the isspace function is 
true, such as spaces and tabs, atol ignores leading white-space characters, digits 
is one or more decimal digits. 


Return Value atol returns a long value produced by interpreting the input characters as a number. 

The return value is 0L if the function cannot convert the input to a value of that type. 
The return value is undefined in case of overflow. 



This example shows how to convert numbers stored as strings to numerical values 
using the atol function. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 

{ 

1ong 1; 
char *s; 

s = "98854 dollars"; 

1 = atol(s); /* 1 = 98854 */ 

printf("atol( %s ) = %d\n", s, 1); 
return 0; 


/**************************************************************************** 

The output should be similar to : 


atol ( 98854 dollars ) = 98854 

****************************************************************************/ 



“atof — Convert Character String to Float” on page 63 
“atoi — Convert Character String to Integer” on page 65 

“_atold — Convert Character String to Long Double” on page 69 

“strtod — Convert Character String to Double” on page 621 

“strtol — Convert Character String to Long Integer” on page 625 

“strtold — Convert String to Long Double” on page 627 
“<stdlib.h>” on page 816 
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atold — Convert Character String to Long Double 

Format linclude <std1ib.h> /* also defined in <math.h> */ 

long double _atold(const char *nptr ); 

Description Language Level: Extension 

_atold converts a character string pointed to by nptr to a long double value. The 
function continues until it reads a character it does not recognize as part of a number. 
This character can be the ending null character. Except for its behavior on error, 
_atol d is equivalent to: 

strtold(nptr, (char **)NULL) 

The string pointed to by nptr must have the following format: 


\-whitespace- 


h- + 


-digits- 


L. —I t—digits—^ 


L - — 1 — digits- 


-digits 




> 


digits is one or more decimal digits. If no digits appear before the decimal point, at 
least one digit must follow the decimal point. You can place an exponent expressed 
as a decimal integer after the digits. The exponent can be signed. 

The value of nptr can also be one of the strings infinity, inf, or nan. These strings 
are case insensitive, and can be preceded by a unary minus (-). They are converted 
to infinity and NaN values. For more information on NaN and infinity values, see 
“Infinity and NaN Support” on page 33. 

_atold ignores any white-space characters, as defined by the isspace function. 

Return Value _atol d returns the converted long double value. In the case of an underflow, it 

returns 0. In the case of a positive overflow, _atol d returns positive _LHUGE_VAL. It 
returns negative _LHUGE_VAL for a negative overflow. 

This example uses _atol d to convert two strings, " -001234.5678el0end of string" 

and "NaNQ", to their corresponding long double values. 



Chapter 3. Library Functions 69 




atold 


#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *string; 

string = " -001234.5678el0end of string"; 

printf("_atold = %.10Le\n", _atold(string)); 
string = "NaNQ"; 

printf("_atold = %.10Le\n", _atold(string)); 
return 0; 

/**************************************************************************** 

The output should be: 

_atold = -1.2345678000e+13 
_atold = nan 

****************************************************************************/ 



“atof — Convert Character String to Float” on page 63 
“atoi — Convert Character String to Integer” on page 65 
“atol — Convert Character String to Long Integer” on page 67 
“strtod — Convert Character String to Double” on page 621 
“strtol — Convert Character String to Long Integer” on page 625 
“strtold — Convert String to Long Double” on page 627 
“<stdlib.h>” on page 816 
“<math.h>” on page 811 
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beginthread — Create New Thread 

Format linclude <stdlib.h> /* also in <process.h> */ 

int _beginthread(void ( *start_address ) (void *), 

(void *)stack, 
unsigned stack_size , 
void *arglist); 

Description Language Level: Extension 

_beginthread creates a new thread. It takes the following arguments: 

start_address This parameter is the address of the function that the newly created 
thread will execute. When the thread returns from that function, it 
is terminated automatically. You can also explicitly terminate the 
thread by calling _endthread. 

stack This parameter is ignored, but is retained to ease migration of C/2 

programs. The C/2 compiler requires the second parameter to be 
the address of the bottom of the stack that the new thread will use. 
Because the OS/2 operating system automatically takes care of 
stack allocation, the parameter is not needed. 

stack_size The size of the stack, in bytes, that is to be allocated for the new 
thread. The stack size should be a nonzero multiple of 4K and a 
minimum of 8K. Memory is used when needed, one page at a 
time. 

arglist A parameter to be passed to the newly created thread. It is the size 

of a pointer, and is usually the address of a data item to be passed 
to the new thread, such as a char string. It provides _beginthread 
with a value to pass to the child thread. NULL can be used as a 
placeholder. 

The function that the new thread will perform must be declared and compiled using 
_OptIink linkage. 

An alternative to this function is the OS/2 DosCreateThread API. If you use 
DosCreateThread, you must also use a fpragma handler statement for the thread 
function to ensure proper C exception handling. You should also call the _fpreset 
function at the start of the thread to preset the 387 control status word correctly. 

Using DosCreateThread requires that you use _endthread to terminate the thread. 

Note: When using the _beginthread and _endthread functions, you must specify 
the /Gm+ compiler option to use the multithread libraries. 
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Return Value 



If successful, _beginthread returns the thread ID number of the new thread. It 
returns -1 to indicate an error. 

This example uses _beginthread to start a new thread bonjour, which prints 
Bonjour! five times and then implicitly ends itself. The program then prints a 
statement indicating the thread identifier number for bonjour. 

Note: To run this example, you must compile it using the /Gm+ compiler option. 

#define INCL_D0S 
#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

static int wait = 1; 

void _0ptlink bonjour(void *arg) 

{ 

int i = 0; 

while (wait) /* wait until the thread id has been printed */ 

DosSleep(Ol); 
while (i++ < 5) 

printf("Bonjour!\n"); 

} 


int main(void) 

{ 

int tid; 

tid = _beginthread(bonjour, NULL, 8192, NULL); 
if (-1 “= tid) { 

printf("Unable to start thread.\n"); 
return EXIT_FAILURE; 

} 

else { 

printf("Thread started with thread identifier number %d.\n", tid); 
wait = 0; 

} 

DosWaitThread((PTID)&tid, DCWW_WAIT); /* wait for thread bonjourto end */ 

/* before ending main thread */ 


return 0; 
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/**************************************************************************** 
The output should be similar to : 

Thread started with thread identifier number 2. 

Bonjour! 

Bonjour! 

Bonjour! 

Bonjour! 

Bonjour! 

****************************************************************************/ 


• “_endthread — Terminate Current Thread” on page 195 

• “_threadstore — Access Thread-Specific Storage” on page 665 

• /Gm+ option in the User's Guide 

• “<stdlib.h>” on page 816 

• “<process.h>” on page 812 
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Bessel Functions — Solve Differential Equations 

Format #include <math.h> 

double _j0(double x); 
double _j1(double x); 
double _jn(int n, double x); 
double _y0(double x); 
double _yl(double x); 
double _yn(int n, double x); 

Description Language Level: SAA 

Bessel functions solve certain types of differential equations. The _j0, _jl, and _jn 
functions are Bessel functions of the first kind for orders 0, 1, and n, respectively. 

The _y0, _yl, and _yn functions are Bessel functions of the second kind for orders 0, 
1, and n, respectively. The argument x must be positive. The argument n should be 
greater than or equal to zero. If n is less than zero, it will be a negative exponent. 


Return Value For _j0, _jl, _y0, or _yl, if the absolute value of x is too large, the function sets 

errno to ERANGE, and returns 0. For _y0, _yl, or _yn, if x is negative, the function sets 
errno to EDOM and returns the value -HUGE_VAL. For _y0, _yl, or _yn, if x causes an 
overflow, the function sets errno to ERANGE and returns the value -HUGE_VAL. 



This example computes y to be the order 0 Bessel function of the first kind for x, and 
z to be the order 3 Bessel function of the second kind for x. 

#include <stdio.h> 

#include <math.h> 


int main(void) 

{ 

double x,y,z; 


x = 4.27; 

y = j0(x); /* y = -0.3660 is the order 0 bessel */ 

/* function of the first kind for x */ 
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printf ("j0( 4.27 ) = %5.4f\n", y); 

z = yn(3, x); /* z = -0.0875 is the order 3 bessel */ 

/* function of the second kind for x */ 

printf("yn( 3,4.27 ) = %5.4f\n“, z); 
return 0; 

/**************************************************************************** 
The output should be: 

j0( 4.27 ) = -0.3660 

yn( 3,4.27 ) = -0.0875 

****************************************************************************/ 


“erf - erfc — Calculate Error Functions” on page 199 
“gamma — Gamma Function” on page 293 
“<math.h>” on page 811 
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bsearch — Search Arrays 

Format linclude <stdlib.h> /* also in <search.h> */ 

void *bsearch(const void *key, const void *base, 
size_t num, size_t size, 

int [*compare) (const void *key, const void *element)); 

Description Language Level: ANSI, SAA, POSIX, XPG, Extension 

bsearch performs a binary search of an array of num elements, each of size bytes. 
The array must be sorted in ascending order by the function pointed to by compare. 
The base is a pointer to the base of the array to search, and key is the value being 
sought. 

The compare argument is a pointer to a function you must supply that takes a pointer 
to the key argument and to an array element , in that order, bsearch calls this 
function one or more times during the search. The function must compare the key 
and the element and return one of the following values: 

Value Meaning 

Less than 0 key less than element 

0 key identical to element 

Greater than 0 key greater than element 


Return Value bsearch returns a pointer to key in the array to which base points. If two keys are 
equal, the element that key will point to is unspecified. If bsearch cannot find the 
key, it returns NULL. 



This example performs a binary search on the argv array of pointers to the program 
parameters and finds the position of the argument PATH. It first removes the program 
name from argv, and then sorts the array alphabetically before calling bsearch. The 
functions compare 1 and compare2 compare the values pointed to by argl and arg2 and 
return the result to bsearch. 
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linclude <stdlib.h> 
linclude <stdio.h> 
linclude <string.h> 


/* - */ 

/* Note: Library always calls functions internally with _0ptlink */ 
/* linkage convention. Ensure that compare!.() and compare2 */ 
/* are always _0ptlink. */ 
/* - */ 


int _0ptlink compare!.(const void *argl,const void *arg2) 

{ 

return (strcmp(*(char **)argl, *(char **)arg2)); 

} 


int _0ptlink compare2(const void *argl,const void *arg2) 

{ 

return (strcmp((char *)argl, *(char **)arg2)); 

} 


int main(int argc,char *argv[]) 

{ 

char **result; 
char *key = "PATH"; 
int i; 
argv++; 
argc--; 

qsort((char *)argv, argc, sizeof(char *), comparel); 

result = (char **)bsearch(key, argv, argc, sizeof(char *), compare2); 

if (result != NULL) { 

printf("result = <%s>\n", *result); 

} 

el se 

printf("result is null\n"); 
return 0; 

^-k-k^k-k-k-k-k-k-k-k^k-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k^k-k 

If the program name is progname and you enter: 
progname where is PATH in this phrase? 

The output should be: 
result = <PATH> 

k-kkkk-k-kkk-k-kkk-k-kkk-kkkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kkk-k-kk/ 

} 

• “1 fi nd - 1 search — Find Key in Array” on page 374 

• “qsort — Sort Array” on page 478 

• “<stdlib.h>” on page 816 
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cabs — Calculate Absolute Value of Complex Number 

Format #include <math.h> 

double _cabs(struct complex z); 

Description Language Level: Extension 

_cabs calculates the absolute value of a complex number. This complex number is 
represented as a structure with the tag complex containing the real and imaginary 
parts. The following type declaration is in <math.h>: 

struct complex {double x,y;}; 

A call to _cabs is equivalent to: 
sqrt(z.x * z.x + z.y * z.y) 

Note: For portability across SAA systems, use the SAA function hypot. to replace 
cabs. 


Return Value _cabs returns the absolute value as a double value. If an overflow results, _cabs 

calls the _matherr routine and, if necessary, sets errno to ERANGE and returns the 
value HUGE VAL. 



The following program computes the absolute value of the complex number (3.0, 
4.0). 


#include <math.h> 

#include <stdio.h> 

int main(void) 

{ 

struct complex value; 
double d; 

value.x = 3.0; 
value.y = 4.0; 
d = _cabs(value); 

printf("The complex absolute value of %f and %f is %f\n", value.x, value.y, d 
); 

return 0; 

/•^■k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k 

The output should be: 

The complex absolute value of 3.000000 and 4.000000 is 5.000000 

•k-k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k'k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k'k-k-k-k-k-k‘k-k-k/ 

} 

• “abs — Calculate Integer Absolute Value” on page 48 

• “fabs — Calculate Floating-Point Absolute Value” on page 207 
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• “hypot — Calculate Hypotenuse” on page 333 

• “labs — Calculate Absolute Value of Long Integer” on page 371 

• “_matherr — Process Math Library Errors” on page 405 

• “sqrt — Calculate Square Root” on page 556 

• “<math.h>” on page 811 
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calloc — Reserve and Initialize Storage 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *calloc(size_t num, size_t size); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

cal 1 oc reserves storage space for an array of num elements, each of length size 
bytes, cal loc then gives all the bits of each element an initial value of 0. 

Heap-specific and tiled versions of this function (_ucalloc and _tcalloc) are also 
available, cal loc always allocates memory from the default heap. You can also use 
the debug version of cal 1 oc, _debug_cal 1 oc, to debug memory problems. 


Return Value cal 1 oc returns a pointer to the reserved space. The storage space to which the 
return value points is suitably aligned for storage of any type of object. To get a 
pointer to a type, use a type cast on the return value. The return value is NULL if 
there is not enough storage, or if num or size is 0. 



This example prompts for the number of array entries required and then reserves 
enough space in storage for the entries. If cal loc is successful, the example prints 
out each entry; otherwise, it prints out an error. 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 
{ 


long *array; 

/* 

start of the array 

*/ 

long *index; 

/* 

index variable 

*/ 

i nt i; 

/* 

index variable 

*/ 

int num; 

/* 

number of entries of 

the array */ 


printf("Enter the size of the array\n"); 
scanf("%i", &num); 
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/* allocate num entries */ 

if ((index = array = calloc(num, sizeof(long))) != NULL) { 

for (i = 0; i < num; ++i) /* put values in array */ 

*index++ = i; /* using pointer notation */ 

for (i = 0; i < num; ++i) /* print the array out */ 

printf("array[ %i ] = %i\n", i, arrayfi]); 

} 

else { /* out of storage */ 

perror("0ut of storage"); 
abort(); 

} 

return 0; 

/**************************************************************************** 
The output should be similar to : 

Enter the size of the array 
3 

array[ 0 ] = 0 
array[ 1 ] = 1 
array[ 2 ] = 2 

****************************************************************************/ 


• “_al loca — Temporarily Reserve Storage Block” on page 53 

• “_debug_cal loc — Allocate and Initialize Memory” on page 139 

• “_debug_tcal 1 oc — Reserve and Initialize Tiled Memory” on page 149 

• “_debug_ucal 1 oc — Reserve and Initialize Memory from User Heap” on 
page 160 

• “free — Release Storage Blocks” on page 263 

• “mal loc — Reserve Storage Block” on page 403 

• “real loc — Change Reserved Storage Block Size” on page 484 

• “_tcal 1 oc — Reserve Tiled Storage Block” on page 647 

• “_ucal 1 oc — Reserve and Initialize Memory from User Heap” on page 686 

• “<malloc.h>” on page 810 

• “<stdlib.h>” on page 816 

• Managing Memory in the Programming Guide 
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cclass — Return Characters in Character Class 

Format linclude <collate.h> 

int cclass(char *class, collel_t **list ); 

Description Language Level: Extension 

cclass finds all the collating elements of the character class , and stores them in an 
array. It then updates the list to point to the first element of the array of found 
collating elements. The list is valid until the next call to setlocale. 

cclass supports POSIX.2 character classes and user-defined character classes. 


Return Value cclass returns the number of elements in the list and sets a pointer to point to the 
list. If the class does not exist in the LC_CTYPE category of the current locale, 
cclass returns -1. 



This example finds all the collating elements that belong to the digit class. It then 
prints how many elements were found in that class and the weight (collating value) of 
each element. 


linclude <stdio.h> 

#include <col1ate.h> 


int main(void) 

{ 

col 1 el_t *list; /* ptr to the digit class collation weights */ 
int weights; /* no. of class collation weights found */ 

int i; 


weights = cclass("digit", Mist); 


printf("weights = %d\n", weights); 
for (i = 0; i < weights; i++) 

printf(" *(list + %d) = %d\n", i, *(1ist + i)); 
return 0; 
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/**************************************************************************** 
The output should be similar to : 


weights = 10 
*(1 i st + 0) = 48 
*(list + 1) = 49 
*(1ist + 2) = 50 
*(list + 3) =51 
*(1 i st + 4) = 52 
*(1ist + 5) = 53 
*(list + 6) = 54 
*(1ist + 7) = 55 
*(list + 8) =56 
*(list + 9) = 57 


****************************************************************************/ 


• “col 1 equi v — Return List of Equivalent Collating Elements” on page 101 

• “col 1 order — Return List of Collating Elements” on page 103 

• “col 1 range — Calculate Range of Collating Elements” on page 105 

• “col 1 tostr — Return String for Collating Element” on page 107 

• “getmccol 1 — Get Next Collating Element from String” on page 306 

• “getwmccol 1 — Get Next Collating Element from Wide String” on page 319 

• “i smccol 1 el — Identify Multi-Character Collating Element” on page 358 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “setl ocal e — Set Locale” on page 530 

• “strtocol 1 — Return Collating Element for String” on page 619 

• “wctype — Get Handle for Character Property Classification” on page 795 

• “<collate.h>” on page 802 

• “<locale.h>” on page 806 
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ceil — Find Integer >= Argument 

Format #include <math.h> 

double cei1(double x ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

cei 1 computes the smallest integer that is greater than or equal to x. 


Return Value ceil returns the integer as a double value. 



This example sets y to the smallest integer greater than 1.05, and then to the smallest 
integer greater than -1.05. The results are 2.0 and -1.0, respectively. 

#include <stdio.h> 

#include <math.h> 


int main(void) 
{ 

double y,z; 


y = ceil(1.05); 

/* y = 2.0 

*/ 

printf("ceil( 1.05 ) = %5.f\n", y); 
z = cei1(-1.05); 

/* z = -1.0 

*/ 


printf("ceil( -1.05 ) = %5.f\n“, z); 
return 0; 

/■******************■*****************************************'*'**'***'*'**'***'*'**'** 
The output should be: 

ceil( 1.05 ) = 2 

ceil{ -1.05 ) = -1 

■k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-kick-k-k-k-kit/ 



“f 1 oo r — Integer <= Argument” on page 239 

“fmod — Calculate Floating-Point Remainder” on page 242 

“<math.h>” on page 811 
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cgets — Read String of Characters from Keyboard 

Format linclude <conio.h> 

char *_cgets(char *str); 

Description Language Level: Extension 

_cgets reads a string of characters directly from the keyboard and stores the string 
and its length in the location pointed to by str. 

_cgets continues to read characters until it meets a carriage return followed by a line 
feed (CR-LF) or until it reads the specified number of characters. It stores the string 
starting at str [2]. If _cgets reads a CR-LF combination, it replaces this combination 
with a null character ( 1 \0 1 ) before storing the string. _cgets then stores the actual 
length of the string in the second array element, str[l]. 

The str variable must be a pointer to a character array. The first element of the 
array, str[0], must contain the maximum length, in characters, of the string to be 
read. The array must have enough elements to hold the string, a final null character, 
and 2 additional bytes. 


Return Value If successful, _cgets returns a pointer to the actual start of the string, s£r[2]. 
Otherwise, _cgets returns NULL. 



This example creates a buffer and initializes the first byte to the size of the buffer. 
The program then accepts an input string using _cgets and displays the size and text 
of that string. 
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#include <conio.h> 

#include <stdio.h> 

void nothing(void) 

{ 

} 

int main(void) 

{ 

char buffer[82] = { 84,0 }; 

char *buffer2; 
i nt i; 

_cputs("\nPress any key to continue."); 
printf("\n"); 
while (0 == _kbhit()) { 
nothing(); 

} 

_getch(); 

_cputs("\nEnter a line of text:"); 

printf("\n"); 

buffer2 = _cgets(buffer); 

printf("\nText entered was: %s", buffer2); 

return 0; 

/**************************************************************************** 

The output should be similar to: 

Press any key to continue. 

Enter a line of text: 

This is a simple test. 

Text entered was: This is a simple test. 


} 


/ 



“_cputs — Write String to Screen” on page 114 
“fgets — Read a String” on page 230 
“gets — Read a Line” on page 309 

“_getch - _getche — Read Character from Keyboard” on page 298 
“<conio.h>” on page 802 
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chdir — Change Current Working Directory 

Format linclude <direct.h> 

int chdir(char *pathname ); 

Description Language Level: XPG4, Extension 

chdir causes the current working directory to change to the directory specified by 
pathname. The pathname must refer to an existing directory. 

Note: This function can change the current working directory on any drive. It 
cannot change the default drive. For example, if A:\BIN is the current working 
directory and A: is the default drive, the following changes only the current working 
directory on drive C:. 
chdir ("c:\\emp"); 

A: is still the default drive. 

An alternative to this function is the DosSetCurrentDi r API call. 

Note: In earlier releases of C Set ++, chdi r began with an underscore (_chdi r). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _chdir to chdir for you. 


Return Value chdi r returns a value of 0 if the working directory was successfully changed. A 
return value of -1 indicates an error; chdir sets errno to ENOENT, showing that 
chdi r cannot find the specified path name. No error occurs if pathname specifies the 
current working directory. 



This example changes the current working directory to the root directory, and then to 
the \red\green\bl ue directory. 

#include <direct.h> 

#include <stdio.h> 


int main(void) 

{ 

printf("Changing to the root directory.\n"): 
if (chdir("\\")) 
perror(NULL); 
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el se 

printf("Changed to the root directory.\n\n"); 
printf("Changing to directory '\\red\\green\\blue 1 .\n"); 
if (chdir("\\red\\green\\blue")) 
perror(NULL); 
else 

printf("Changed to directory '\\red\\green\\blue'.\n"); 
return 0; 

^•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-ki<‘k-k-k‘k-k-k‘k-k-k‘J(-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k-k-k-k‘k-k-k‘k-k-k-k 

If directory \red\green\blue exists, the output should be: 

Changing to the root directory. 

Changed to the root directory. 

Changing to directory '\red\green\blue'. 

Changed to directory 1 \red\green\blue 1 . 

■k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-kick-k-k-k-k-k-k-k-k-k-k-k/ 

} 



“_chdrive — Change Current Working Drive” on page 89 

“_getcwd — Get Path Name of Current Directory” on page 300 

“_getdcwd — Get Full Path Name of Current Directory” on page 302 

“_getdrive — Get Current Working Drive” on page 304 

“system — Invoke the Command Processor” on page 639 

“mkdi r — Create New Directory” on page 436 

“rmdi r — Remove Directory” on page 499 

“system — Invoke the Command Processor” on page 639 

“<direct.h>” on page 803 
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chdrive — Change Current Working Drive 

Format linclude <direct.h> 

int _chdrive(int drive); 

Description Language Level: Extension 

_chdrive changes the current working drive to the drive specified. The drive 
variable is an integer value representing the number of the new working drive (A: is 
1, B: is 2, and so on). 

To change the default drive, include <os2.h>, define INCL_DOSFILEMGR, and use 
DosSetDefaul tDi sk to pass the appropriate command to the operating system. You 
can also use DosQueryCurrentDisk to query the disk. For more information, refer to 
the Control Program Guide and Reference. 

Return Value _chdrive returns Q if it is successful in changing the working drive. A return 
value of -1 indicates an error; _chdrive sets errno to EOS2ERR. 

This example uses _chdrive to change the current working drive to C:. 


#include <direct.h> 

#include <stdio.h> 

int main(void) 

{ 

if (_chdrive(3)) 

printf("Cannot change current working drive to 'C' drive.\n"); 
el se { 

printf("Current working drive changed to "); 
printf(" 1 %c 1 drive.\n", ( 1 A'+_getdrive()-1)); 

} 

return 0; 

/**************************************************************************** 
The output should be similar to : 

Current working drive changed to 'C' drive. 
****************************************************************************/ 
i 

• “chdi r — Change Current Working Directory” on page 87 

• “_getcwd — Get Path Name of Current Directory” on page 300 

• “_getdcwd — Get Full Path Name of Current Directory” on page 302 

• “_getdrive — Get Current Working Drive” on page 304 

• “mkdi r — Create New Directory” on page 436 

• “rmdi r — Remove Directory” on page 499 

• “<direct.h>” on page 803 
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chmod — Change File Permission Setting 

Format linclude <io.h> 

linclude <sys\stat.h> 

int chmod(char *pathname, int pmode ); 

Description Language Level: XPG4, Extension 

chmod changes the permission setting of the file specified by pathname. The 
permission setting controls access to the file for reading or writing. You can use 
chmod only if the file is closed. 

The pmode expression contains one or both of the constants S_IWRITE and 
S_IREAD, defined in <sys\stat.h>. The meanings of the values of pmode are: 

Value Meaning 

S_IREAD Reading permitted 

S_IWRITE Writing permitted 

S_IREAD I S IWRITE Reading and writing permitted. 

If you do not give permission to write to the file, chmod makes the file read-only. 
With the OS/2 operating system, all files are readable; you cannot give write-only 
permission. Thus, the modes S_IWRITE and S_IREAD I S_IWRITE set the same 
permission. 

Specifying a pmode of S_1READ is similar to making a file read-only with the 
ATTRIB system command. 

Note: In earlier releases of C Set ++, chmod began with an underscore (_chmod). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _chmod to chmod for you. 


Return Value chmod returns the value 0 if it successfully changes the permission setting. A return 
value of -1 shows an error; chmod sets errno to one of the following values: 

Value Meaning 

ENOENT The system cannot find the file or the path that you specified, or the file 
name was incorrect. 

EOS2ERR The call to the operating system was not successful. 

EINVAL The mode specified was not valid. 



This example opens the file chmod.dat for writing after checking the file to see if 
writing is permissible. It then writes from the buffer to the opened file. This 
program takes file names passed as arguments and sets each to read-only. 
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linclude <sys\stat.h> 

#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

if (-1 == access("chmod.dat", 00)) /* Check if file exists. */ 

{ 

printf("\nCreating chmod.dat.\n"); 
system("echo Sample Program > chmod.dat"); 
printf("chmod chmod.dat to be readonly.\n"); 
if (-1 == chmod("chmod.dat", S_IREAD)) 
perror("Chmod failed"); 
if (-1 == access("chmod.dat", 02)) 

printf("Fi1e chmod.dat is now readonly.\n\n"); 
printf("Run this program again to erase chmod.dat.\n\n"); 

} 

el se { 

printf("\nFile chmod.dat exist.\n"); 
printf("chmod chmod.dat to become writable.\n"); 
if (-1 == chmod("chmod.dat", S_IWRITE)) 
perror("Chmod failed"); 
system("erase chmod.dat"); 
printf("File chmod.dat removed.\n\n"); 

} 

return 0; 

/**************************************************************************** 
If chmod.dat does not exist, the output should be : 

Creating chmod.dat. 

chmod chmod.dat to be readonly. 

File chmod.dat is now readonly. 

Run this program again to erase chmod.dat. 
****************************************************************************/ 

} 


• “access — Determine Access Mode” on page 49 

• “_sopen — Open Shared File” on page 545 

• “umask — Sets File Mask of Current Process” on page 719 

• “<sys\stat.h>” on page 819 

• “<io.h>” on page 804 
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chsize — Alter Length of File 

Format linclude <io.h> 

int _chsize(int handle, long size)-. 

Description Language Level: Extension 

_chsize lengthens or cuts off the file associated with handle to the length specified 
by size. You must open the file in a mode that permits writing. _chsize adds null 
characters (\0) when it lengthens the file. When _chsize cuts off the file, it erases 
all data from the end of the shortened file to the end of the original file. 

Return Value _chsize returns the value 0 if it successfully changes the file size. A return value 
of -1 shows an error; _chsize sets errno to one of the following values: 

Value Meaning 

EACCESS The specified file is locked against access. 

EBADF The file handle is not valid, or the file is not open for writing. 

ENOSPC There is no space left on the device. 

EOS2ERR The call to the operating system was not successful. 

This example opens a file named sample.dat and returns the current length of that 
file. It then alters the size of sample.dat and returns the new length of that file. 

linclude <io.h> 
linclude <stdio.h> 
linclude <stdlib.h> 
linclude <fcntl.h> 

int main(void) 

{ 

long length; 
int fh; 

printf("\nCreating sample.dat.\n"); 
system("echo Sample Program > sample.dat"); 
if (-1 == (fh = open("sample.dat", 0_RDWR|0_APPEND))) { 
printf("Unable to open sample.dat.\n"); 
return EXIT_FAILURE; 

} 

if (-1 == (length = fi1 elength(fh))) { 

printf("Unable to determine length of sample.dat.\n"); 
return EXIT_FAILURE; 

} 
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printf("Current length of sample.dat is %d.\n", length); 

printf("Changing the length of sample.dat to 20.\n"); 

if (-1 == (_chsize(fh, 20))) { 
perror("chsize failed' 1 ); 
return EXIT_FAILURE; 

} 

if (-1 == (length = _filelength(fh))) { 

printf("Unable to determine length of sample.dat.\n"); 
return EXIT_FAILURE; 

} 

printf("New length of sample.dat is %d.\n", length); 

close(fh); 

return 0; 

/**************************************************************************** 
The output should be similar to : 

Creating sample.dat. 

Current length of sample.dat is 17. 

Changing the length of sample.dat to 20. 

New length of sample.dat is 20. 

****************************************************************************/ 

} 


• “_fi 1 el ength — Determine File Length” on page 236 

• “1 seek — Move File Pointer” on page 393 

• “<io.h>” on page 804 
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clearerr — Reset Error Indicators. 

Format linclude <stdio.h> 

void clearerr (FILE *stream); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

The clearerr function resets the error indicator and end-of-file indicator for the 
specified stream. Once set, the indicators for a specified stream remain set until 
your program calls clearerr or rewind, fseek also clears the end-of-file indicator. 

Return Value There is no return value. 

This example reads a data stream and then checks that a read error has not occurred. 

linclude <stdio.h> 
linclude <stdlib.h> 

FILE *stream; 
int c; 

int main(void) 

{ 

if (NULL != (stream = fopen("fi1e.dat", "r"))) { 
if (EOF == (c = getc(stream))) { 
if (feof(stream)) { 
perror("Read error"); 
clearerr(stream); 



} 

return 0; 

/•k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k-k-k-k‘k-k-k-k-k-k-k 

If file.dat is an empty file, the output should be: 

Read error: Attempted to read past end-of-file. 

i 

• “feof — Test End-of-File Indicator” on page 222 

• “ferror — Test for Read/Write Errors” on page 223 

• “perror — Print Error Message” on page 459 

• “rewi nd — Adjust Current File Position” on page 497 

• “strerror — Set Pointer to Runtime Error Message” on page 579 

• “_strerror — Set Pointer to System Error String” on page 580 

• “<stdio.h>” on page 815 
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_clear87 — 

Format 

Description 

Return Value 



Clear Floating-Point Status Word 

linclude <float.h> /* also in <builtin.h> */ 
unsigned int _clear87(void); 

Language Level: Extension 

_clear87 gets the floating-point status word and then clears it. The floating-point 
status word is a combination of the numeric coprocessor status word and other 
conditions that the numeric exception handler detects, such as floating-point stack 
overflow and underflow. 

_clear87 affects only the current thread. It does not affect any other threads that 
may be processing. 

The bits in the value returned reflect the floating-point status before the call to 
_clear87 was made. 

This example takes a number close to 0 as a double and assigns it to a float. The 
result is a loss of significance, y becomes a denormal number, and the underflow bit 
of the floating-point status word is set. _clear87 gets the current floating-point 
status word and then clears it, and printf prints it as immediate data. The result 
shows the change in the floating-point word because of the loss of significance. 

The program then assigns the denormal y to another variable, causing the denormal 
bit to be set in the floating-point status word. Again, _cl ear87 gets the current 
status word and clears it, and printf prints it to the screen. 

#include <stdio.h> 

#include <float.h> 

double a = le-40; 
double b; 
float y; 

int main(void) 

{ 

unsigned int statword; 
unsigned int old_cw; 
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/* change control word to mask all exceptions */ 

_control87(0x037f, 0xffff); 

/* Assignment of the double to the float y is inexact; */ 

/* the underflow bit is set. */ 

y = a; 

statword = _clear87(); 

printf("floating-point status = 0x%.4x after underflow\n", statword); 
statword = _status87(); 

printf("cleared floating-point status word = 0x%.4x\n", statword); 


/* reset floating point status word */ 

_fpreset(); 

/* change control word to mask all exception */ 

_control87(0x037f, 0xffff); 

/* Reassigning the denormal y to the double b */ 

/* causes the denormal bit to be set. */ 

b = y; 

statword = _clear87(); 


printf("floating-point status = 0x%.4x for denormal\n“, statword); 

/* reset floating point status word */ 

_fpreset(); 
return 0; 

/**************************************************************************** 

The output should be: 

floating-point status = 0x0030 after underflow 
cleared floating-point status word = 0x0000 
floating-point status = 0x0002 for denormal 
****************************************************************************/ 

} 


“_control87 — Set Floating-Point Control Word” on page 109 
“_status87 — Get Floating-Point Status Word” on page 563 
“_fpreset — Reset Floating-Point Unit” on page 247 
• “<float.h>” on page 803 
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clock — Determine Processor Time 

Format linclude <time.h> 

clock_t clock(void); 

Description Language Level: ANSI, SAA, XPG4 

clock returns an approximation of the processor time used by the program since the 
beginning of an implementation-defined time-period that is related to the program 
invocation. To obtain the time in seconds, divide the value returned by clock by the 
value of the macro CLOCKS PER SEC. 


Return Value If the value of the processor time is not available or cannot be represented, clock 
returns the value (c 1 o c k_t) -1. 

To measure the time spent in a program, call clock at the start of the program, and 
subtract its return value from the value returned by subsequent calls to clock. 

This example prints the time elapsed since the program was invoked. 

#i nc1ude <time.h> 

#inc1ude <stdio.h> 

double timel,time2,timedif; /* use doubles to show small values */ 

i nt i; 

int main(void) 

{ 

timel = (double)clock(); /* get initial time in seconds */ 

timel = timel/CLOCKS_PER_SEC; 

/* use some CPU time */ 

for (i = 0; i < 5000000; i++) { 
int j; 

j = i; 

} 

time2 = (double)clock(); /* call clock a second time */ 

time2 = time2/CL0CKS_PER_SEC; 
timedif = time2-timel; 

printf("The elapsed time is %f seconds\n", timedif); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

The elapsed time is 0.969000 seconds 

****************************************************************************/ 

i 

• “difftime — Compute Time Difference” on page 166 
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• “t i me — Determine Current Time” on page 666 

• “<time.h>” on page 819 
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close — Close File Associated with Handle 

Format linclude <io.h> 

int close(int handle ); 

Description Language Level: XPG4, Extension 

close closes the file associated with the handle. Use close if you opened the handle 
with open. If you opened the handle with fopen, use fclose to close it. 

Note: In earlier releases of C Set ++, close began with an underscore (_close). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _close to close for you. 

Return Value close returns 0 if it successfully closes the file. A return value of -1 shows an 

error, and close sets errno to EBADF, showing an incorrect file handle argument. 

This example opens the file edclose.dat and then closes it using the close function. 

#inc1ude <io.h> 

#inc1ude <stdio.h> 

#i nc1ude <fcntl.h> 
linclude <sys\stat.h> 

#inc1ude <stdlib.h> 

int main(void) 

{ 

int fh; 

printf("\nCreating edclose.dat.\n"); 

if (-1 == (fh = openC'edclose.dat", 0_RDWR|0_CREAT|0_TRUNC, S_IREAD|S_IWRITE) 

)) { 

perror("Unable to open edclose.dat"); 
return EXIT_FAILURE; 

} 

printf("Fi1e was successfully opened.\n"); 
if (-1 == close(fh)) { 

perror("tlnable to close edclose.dat"); 
return EXIT_FAILURE; 

} 

printf("Fi1e was successfully closed.\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

Creating edclose.dat. 

File was successfully opened. 

File was successfully closed. 

****************************************************************************/ 

} 

• “fclose — Close Stream” on page 212 

• “creat — Create New File” on page 115 
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• “open — Open File” on page 447 

• “_sopen — Open Shared File” on page 545 

• “<io.h>” on page 804 
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col 1equiv 

Format 

Description 


Return Value 



Return List of Equivalent Collating Elements 

linclude <collate.h> 

int col 1equiv(col1 el_t c, collel_t **list ); 

Language Level: Extension 

collequiv finds all the collating elements that have the same primary weight as c, 
and stores them in an array. (The primary weight is the initial value used to 
determine how the character is collated or ordered.) It then updates the list to point 
to the first element of the array of found collating elements. 

The list of elements is valid until the next call to setlocale with categories 
LC_ALL, LC_COLLATE, or LC_CTYPE. Another call to collequiv could override 
the current list. 

Notes: 

1. If c has the weight IGNORE in the LC_COLLATE category, the list created 
contains all the characters specified as IGNORE. 

2. The list contains only characters defined in the charmap file in the current locale. 

3. The list is built statically in the locale, and is freed when the locale is deleted. 

col 1 equi v returns the number of collating elements with the equivalent weight. If 
the value of c is not in the valid range of collating elements in the current locale, 
collequiv returns -1. 

This example prints the collating elements that have an equivalent weight as the 
collating element passed in argv[l]. 

#include <stdio.h> 

#include <1ocale.h> 

#inc1ude <col1 ate.h> 

#include <wchar.h> 

int main(int argc, char *argv[]) 

{ 

coll el_t e, *rp; 
int i; 
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setlocale(LC_ALL, LC_C_FRANCE); 
if ((collel_t)-l == (e = strtocol1(argv[1]))) { 

printf("'%s 1 collating element not defined\n", argv[1]); 
exit(l); 

} 

if (-1 == (i = collequiv(e, &rp))) { 

printf("Invalid collating element '%s'\n", argv[l]); 
exit(l); 


for (; i >0; rp++, i--) { 
if (ismccol 1 el (*rp)) 

printf(" 1 %s 1 ", col 1tostr(*rp)); 
else if (iswprint(*rp)) 

printf("'%1 c' ", *rp); 
else 

printf('"%x' ", *rp); 


return 0; 

/**************************************************************************** 
Assuming you compile this example as collequi.exe 
and invoke it as: collequi * 

The output should be: 

'Du 1 'Des ' 'De 1 'D 11 'Les ' 1 Le ' 'La ' 1 L ' 1 'du 1 'des ' 1 de ' 

. d '' '] es ' 1e ' 'la 1 ' 1 1 ' 

****************************************************************************/ 



“cclass — Return Characters in Character Class” on page 82 
“col 1 order — Return List of Collating Elements” on page 103 
“col 1 range — Calculate Range of Collating Elements” on page 105 
“col 1 tostr — Return String for Collating Element” on page 107 
“getmccol 1 — Get Next Collating Element from String” on page 306 
“getwmccol 1 — Get Next Collating Element from Wide String” on page 319 
“i smccol 1 el — Identify Multi-Character Collating Element” on page 358 
“maxcol 1 — Return Maximum Collating Element” on page 409 
“strtocol 1 — Return Collating Element for Suing” on page 619 
“<collate.h>” on page 802 
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col 1 order 

Format 

Description 


Return Value 



Return List of Collating Elements 

linclude <collate.h> 

int col 1order(col1 el_t **list ); 

Language Level: Extension 

col 1 order finds the number of collating elements in the collate order list and sets 
list to point to the collate order list. The list returned is valid until another call to 
setl ocal e. 

Notes: 

1. Collating elements specified with the weight of IGNORE in the LC_COLLATE 
category are defined as having the lowest weight. 

2. The list contains only characters defined in the charmap file in the current locale. 

3. The list is built statically in the locale, and is freed when the locale is deleted. 

col 1 order returns the number of collating elements in the collate order list. 

This example uses col 1 order to create a list of all the collating elements. 

#inc1ude <stdio.h> 

#include <1ocale.h> 

#include <col1 ate.h> 

#inc1ude <wchar.h> 

int main(void) 

{ 

collel_t *rp; 
int i; 

setlocale(LC_ALL, LC_C_FRANCE); 
i = col 1order(&rp); 
for (; i >0; rp++, i--) { 
i f (ismccol1 el(*rp)) 

printf(" 1 %s 1 ", col 1tostr(*rp)); 
else if (iswprint(*rp)) 

printf(" 1 %1c' ", *rp); 
el se 

printf("'%x' ", *rp); 

} 
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return 0; 

/**************************************************************************** 

The output should be similar to : 


1 1 '!.#' '$' '%' 

'Les 1 1 Le 1 'La 1 'L" 

'+' •,' '/' 

' 0 ' ' 1 ' ' 2 ' ' 3 ' ' 4 ' ' 5 ' 

'0' 'A' 'B 1 'C' 1 D' 1 E 1 

'P' 1 Q' 'R 1 'S' 1 T' 1 U 1 

****************************************************************************/ 


• “ccl ass — Return Characters in Character Class” on page 82 

• “col 1 equi v — Return List of Equivalent Collating Elements” on page 101 

• “col 1 range — Calculate Range of Collating Elements” on page 105 

• “colltostr — Return Suing for Collating Element” on page 107 

• “getmccol 1 — Get Next Collating Element from Suing” on page 306 

• “getwmccol 1 — Get Next Collating Element from Wide Suing” on page 319 

• “i smccol 1 el — Identify Multi-Character Collating Element” on page 358 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “strtocol 1 — Return Collating Element for Suing” on page 619 

• “<collate.h>” on page 802 


'&' 1 (.)' '*' 'Du ' 'Des ' 'De 1 'D" 

'du ' 'des ' 'de ' 'd 11 'les ' 'le ' 'la ' 'I ' 1 

'6' '7' '8' '9' ':' ';' '<' ' = ' '>' '?' 

' F 1 ' G' ' H ' 'I' 'J' 1 K' 'L 1 'M' 'N' '0' 

'V' 'W 'X' 'Y' 'Z' '[' 'V ']' '_' 
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col 1 range 

Format 

Description 


Return Value 



Calculate Range of Collating Elements 

linclude <collate.h> 

int col 1 range(col 1 el_t start, collel_t end, collel_t **list ); 

Language Level: Extension 

col 1 range finds the collating elements whose primary weights are between the 
start and end elements, inclusive, and stores them in an array. It then updates list 
to point to the array of found collating elements. The list is valid until the next call 
to setlocale. 

Notes: 

1. Collating elements specified with the weight of IGNORE in the LC_COLLATE 
category are defined as having the lowest weight. Therefore, such elements can 
only be specified as the starting collating element. 

2. The list contains only characters defined in the charmap file in the current locale. 

3. The list is built statically in the locale and is freed when the locale is deleted. 

col 1 range returns the number of elements that fall between the range of weights. 

If the end point collates earlier than the start point, col 1 range returns 0. If either 
start or end are out of range, col 1 range returns -1. It does not set errno. 

This example uses col 1 range to print the collating elements in the range passed in 
argv[l] and argv[2]. 

#include <stdio.h> 

#inc1ude <1ocale.h> 

#include <col1 ate.h> 
line!ude <wchar.h> 

int main(int arge, char *argv[]) 

{ 

coll el_t s, e, *rp; 
int i; 

setlocale(LC_ALL, LC_C_FRANCE); 

if ((col 1el_t)-1 == (s = strtocol1(argv[1]))) { 

printf(" 1 %s 1 collating element not defined\n", argv[1]); 
exit(l); 

} 
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if ((col 1el_t)-l == (e = strtocol 1 (argv[2]))) { 

printf("'%s' collating element not defined\n", argv[2]); 
exit(l); 

} 

if (-1 == (i = collrange(s, e, &rp))) { 

printf("Invalid range for '%s' to ’%s 1 \n", argv[l], argv[2]); 
exit(l); 



for (; i >0; rp++, i--) { 
i f (ismccol1 el(*rp)) 

printf(" 1 %s' ", col 1tostr(*rp)); 
else if (iswprint(*rp)) 

printf(" 1 %1c 1 ", *rp); 
el se 

printf('"%x' ", *rp); 

} 

return 0; 


/**************************************************************************** 
Assuming you compile this example as collrang.exe 
and invoke it as: collrang A z 


The output should be: 


'A' 
'S' 
' e' 
'w' 


1 B' 
1 T' 
' f' 
' x' 


' D 1 
■V 
' h 1 
' z' 


' E' 
'W' 
' i' 


' G ’ 
' Y' 
' k 1 


' H' 
' Z' 
'1 ' 


' J' 

■v 

1 n 1 


'Q' 
' c' 
1 u 1 


■kle-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-kle-k-k-k-k-kle-k-k'k-k-k'k-k-k-k-k-k-k-k-kle-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k/ 


• “ccl ass — Return Characters in Character Class” on page 82 

• “col 1 equi v — Return List of Equivalent Collating Elements” on page 101 

• “col 1 order — Return List of Collating Elements” on page 103 

• “colltostr — Return String for Collating Element” on page 107 

• “getmccol 1 — Get Next Collating Element from String” on page 306 

• “getwmccol 1 — Get Next Collating Element from Wide String” on page 319 

• “i smccol 1 el — Identify Multi-Character Collating Element” on page 358 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “strtocol 1 — Return Collating Element for String” on page 619 

• “<collate.h>” on page 802 
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col 1tostr 

Format 

Description 


Return Value 



Return String for Collating Element 

linclude <collate.h> 
char *col 1 tostr(col 1el_t c); 

Language Level: Extension 

col 1 tostr is the inverse of strtocol 1; it converts the collating element c to the 
string for that collating element. 

You could use the returned array from col 1 range or col 1 equi v and call i smccol 1 el 
for each element, only calling col 1 tostr if i smccol 1 el is true for the element. 

The string returned is valid until another call to setlocale. 

Note: The string is built statically in the locale and is freed when the locale is 
deleted. 


col 1 tostr returns the string for the collating element. If c is a single character or 
out of range, col 1 tostr returns NULL. 

This example prints all the collating elements in the collating sequence, using 
colltostr to get the string for the multi-character collating elements. 

#include <stdio.h> 

#include <1ocale.h> 

#include <col1 ate.h> 

#inc1ude <wchar.h> 

int main(void) 

{ 

collel_t *rp; 
int i; 

setlocale(LC_ALL, LC_C_FRANCE); 
i = col 1order(&rp); 
for (; i >0; rp++, i--) { 
i f (ismccol1 el(*rp)) 

printf(" 1 %s 1 ", col 1tostr(*rp)); 
else if (iswprint(*rp)) 

printf("'%!c' ", *rp); 
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el se 

printf('"%x' ", *rp); 



return 0; 

/**************************************************************************** 

The output should be similar to : 


1 1 1 !.#' 1 &dol 1 ar' '%' '&' '(' '" 

'Les 1 1 Le 1 'La 1 'L 1 ' 'du 1 'des 1 1 de 1 
'+' '/' 

' 0 ' ' 1 ' ' 2 ' ' 3 ' ' 4 ' ' 5 ' ' 6 ' ' 7 ' ' 8 ' ' 9 ' 

'A' ‘ B' 'C' ' D 1 'E' ' F 1 1 G' 1 H' 'I' 'J 

' P' 1 Q' 1 R 1 'S' 1 T' 'U' 'V' 'W' 'X' 1 Y 1 'Z 

****************************************************************************/ 


• “ccl ass — Return Characters in Character Class” on page 82 

• “col 1 equi v — Return List of Equivalent Collating Elements” on page 101 

• “col 1 order — Return List of Collating Elements” on page 103 

• “col 1 range — Calculate Range of Collating Elements” on page 105 

• “colltostr — Return String for Collating Element” on page 107 

• “getmccol 1 — Get Next Collating Element from String” on page 306 

• “getwmccol 1 — Get Next Collating Element from Wide String” on page 319 

• “i smccol 1 el — Identify Multi-Character Collating Element” on page 358 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “strtocol 1 — Return Collating Element for String” on page 619 

• “<collate.h>” on page 802 


')' 1 *' 'Du ' 'Des ' 'De 1 'D' 

'd" 'les ' 'le ' 'la ' '1 " 

. I . I I = l l>l 

' 'K' 'L 1 'M' 'N' ' 0 ' 

' '[' 'V ']' '~' '_' 


108 VisualAge C++ C Library Reference 




control87 


_control87 

Format 

Description 


Return Value 


- Set Floating-Point Control Word 

linclude <float.h> /* also in <builtin.h> */ 

unsigned int _control87(unsigned int new, unsigned int mask); 

Language Level: Extension 

_control87 gets the current floating-point control word and then sets it. The 
floating-point control word specifies the precision, rounding, and infinity modes of 
the floating-point chip. 

You can mask or unmask current floating-point exceptions using _control87. If the 
value for the mask is equal to 0, _control87 gets the floating-point control word. If 
the mask is nonzero, _contro!87 sets a new value for the control word in the manner 
described below, and returns the previous value of the control word. For any bit in 
the mask equal to 1, the corresponding bit in new updates the control word. This is 
equivalent to the expression: 

fpcntrl = ((fpcntrl & " mask ) | (new & mask)) 
where fpcntrl is the floating-point control word. 

-Control87 is used for the current thread only. It does not affect any other threads 
that may be processing. 

Warning: If you change the content of the floating-point control word: 

• The behavior of the math functions with regard to domain and range errors may 
be undefined. 

• Math functions may not handle infinity and NaN values correctly. 

• Some floating-point exceptions may not occur, while other new ones may occur. 

• Resetting the EM_INEXACT bit may cause SIG_FPE exceptions, which decrease 
performance. 

• If the precision or rounding bits are modified, you can reduce the precision 
available for float and double variables. 

For information on bits in the control word and handling floating-point exceptions, 
see the User's Guide. 

The bits in the returned value reflect the floating-point control word before the call. 
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This example prints the initial control word in hexadecimal, and then illustrates 
different representations of 0.1, depending on the precision. 

#include <stdio.h> 

#include <float.h> 


double a = .13; 

int main(void) 

{ 

printf("control = 0x%.4x\n", _control87(CW_DEFAULT, 0));/* Get control word*/ 
printf("a*a = .0169 = %.15e\n", a *a); 

_control87(PC_24, MCW_PC); /* Set precision to 24 bits */ 

printf("a*a = .0169 (rounded to 24 bits) = %.15e\n", a *a); 

_control87(CW_DEFAULT, 0xffff); /* Restore to initial default */ 

printf("a*a = .0169 = %.15e\n", a *a); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

control = 0x0362 

a*a = .0169 = 1.69O00O00O00O00Oe-O2 

a*a = .0169 (rounded to 24 bits) = 1.690000057220459e-02 

a*a = .0169 = 1.6900000O0000000e-02 

****************************************************************************/ 

} 



“_cl ear87 — Clear Floating-Point Status Word” on page 95 
“_status87 — Get Floating-Point Status Word” on page 563 
“_fpreset — Reset Floating-Point Unit” on page 247 
Floating Point Variables 

“signal — Handle Interrupt Signals” on page 540 
“<float.h>” on page 803 
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cos — Calculate Cosine 

Format linclude <math.h> 

double cos(double x ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

cos calculates the cosine of x. The value x is expressed in radians. If x is too large, 
a partial loss of significance in the result may occur. 

Return Value cos returns the cosine of x. 

This example calculates y to be the cosine of x. 

#include <math.h> 

int main(void) 

{ 

double x,y; 

x = 7.2; 
y = cos(x); 

printf("cos( %lf ) = %lf\n", x, y); 
return 0; 

/**************************************************************************** 

The output should be: 

cos( 7.200000 ) = 0.608351 

****************************************************************************/ 

} 

• “acos — Calculate Arccosine” on page 51 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_facos — Calculate Arccosine” on page 208 

• “_fcos — Calculate Cosine” on page 214 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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cosh — Calculate Hyperbolic Cosine 

Format linclude <math.h> 

double cosh(double x) ; 

Description Language Level: ANSI, SAA, POSIX, XPG4 

cosh calculates the hyperbolic cosine of x. The value x is expressed in radians. 

Return Value cosh returns the hyperbolic cosine of x. If the result is too large, cosh returns the 
value HUGE_VAL and sets errno to ERANGE. 

This example calculates y to be the hyperbolic cosine of x. 
linclude <math.h> 

int main(void) 

{ 

double x,y; 

x = 7.2; 
y = cosh(x); 

printf("cosh( %lf ) = %lf\n", x, y) ; 
return 0; 

/•k-k-klt-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-klck-k-k-k-k-k-kick-k-k-k 

The output should be: 
cosh( 7.200000 ) = 669.715755 

ie'k-k-kle-k-kle-k-k'k-k-kle-k-kle-k-k'k-k-k-k-k-k-k-k-k'k-k-kle-kitle-k-kle-k-kle-k-k'k-k-kic-k-k-k-k-kle-k-k'k-k-kle-k-kle-k-kle-k-k'k-k-k-k-k-kle-k-k/ 

} 

• “acos — Calculate Arccosine” on page 51 

• “cos—Calculate Cosine” on page 111 

• “_facos — Calculate Arccosine” on page 208 

• “_fcos — Calculate Cosine” on page 214 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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cprintf — Print Characters to Screen 

Format linclude <conio.h> 

int _cprintf(char *format-string , argument-list); 

Description Language Level: Extension 

_cprintf formats and sends a series of characters and values directly to the screen, 
using the _putch function to send each character. 

Th e format-string has the same form and function as the format-string 
parameter for printf. Format specifications in the format-string determine the 
output format for any argument-1 ist that follows. See “pri ntf — Print Formatted 
Characters” on page 461 for a description of the format-string. 

Note: Unlike the fprintf, printf, and sprintf functions, _cprintf does not 
translate line feed characters into output of a carriage return followed by a line feed. 

Return Value _cprintf returns the number of characters printed. 

The following program uses _cprintf to write strings to the screen. 

#include <conio.h> 

int main(void) 

{ 

char buffer[24]; 

_cprintf("\nPlease enter a filename:\n"); 

_cscanf("%23s", buffer); 

_cprintf("\nThe file name you entered was %23s.", buffer); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

Please enter a filename: 

fi1e.dat 

The filename you entered was file.dat. 

****************************************************************************/ 

} 

• “_cscanf — Read Data from Keyboard” on page 127 

• “fpri ntf — Write Formatted Data to a Stream” on page 249 

• “pri ntf — Print Formatted Characters” on page 461 

• “_putch — Write Character to Screen” on page 470 

• “spri ntf — Print Formatted Data to Buffer” on page 554 

• “<conio.h>” on page 802 
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cputs — Write String to Screen 

Format linclude <conio.h> 

int _cputs(char *str); 

Description Language Level: Extension 

_cputs writes the string that str points to directly to the screen. The string str 
must end with a null character (\0). The _cputs function does not automatically add 
a carriage return followed by a line feed to the string. 

Return Value If successful, _cputs returns 0. Otherwise, it returns a nonzero value. 

This example outputs a prompt to the screen. 

linclude <conio.h> 

int main(void) 

{ 

char *buffer = "Insert data disk in drive a: \r\n"; 

_cputs(buffer); 
return 0; 

/•k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-kle-k-k-k-k-klck-k-k-k-k-k-k-k'k-k-k-k 

The output should be: 

Insert data disk in drive a: 

i 




“_cgets — Read String of Characters from Keyboard” on page 85 

“fputs — Write String” on page 255 

“_putch — Write Character to Screen” on page 470 

“puts — Write a String” on page 473 

“<conio.h>” on page 802 
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creat — Create New File 

Format linclude <io.h> 

linclude <sys\stat.h> 

int creat(char * pathname , int pmode); 

Description Language Level: XPG4, Extension 

creat either creates a new file or opens and truncates an existing file. If the file 
specified by pathname does not exist, creat creates a new file with the given 
permission setting and opens it for writing in text mode. If the file already exists, 
and the read-only attribute and sharing permissions allow writing, creat truncates the 
file to length 0. This action destroys the previous contents of the file and opens it for 
writing in text mode, creat always opens a file in text mode for reading and 
writing. 

The permission setting pmode applies to newly created files only. The new file 
receives the specified permission setting after you close it for the first time. The 
pmode integer expression contains one or both of the constants S_IWRITE and 
S_IREAD, defined in <sys\stat.h>. The values of the pmode argument and their 
meanings are: 

Value Meaning 

SIREAI) Reading permitted 

S_IWRITE Writing permitted 

S IREAI) I S IWRITE Reading and writing permitted. 

If you do not give permission to write to the file, it is a read-only file. On the OS/2 
operating system, you cannot give write-only permission. Thus, the modes 
S_IWRITE and S_IREAD I S_IWRITE have the same results. The creat function 
applies the current file permission mask to pmode before setting the permissions. 

(See “umask — Sets File Mask of Current Process” on page 719 for more 
information about file permission masks.) 

When writing new code, you should use open rather than creat. 

Specifying a pmode of S_IREAD is similar to making a file read-only with the 
ATTRIB system command. 

Note: In earlier releases of C Set ++, creat began with an underscore (_creat). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _creat to creat for you. 
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Return Value creat returns a handle for the created file if the call is successful. A return value 
of -1 shows an error, and creat sets errno to one of the following values: 

Value Meaning 

EACCESS File sharing violated. 

EINVAL The mode specified was not valid. 

EMFILE No more file handles are available. 

ENOENT The path name was not found, or the file name was incorrect. 
EOS2ERR The call to the operating system was not successful. 

This example creates the file sample.dat so it can be read from and written to. 


linclude <sys\stat.h> 

#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

int fh; 

fh = creat("sample.dat", S_IREAD|S_IWRITE); 
if (-1 == fh) { 

perror("Error in creating sample.dat"); 
return EXIT_FAILURE; 

} 

else 

printf("Successfully created sample.dat.\n"); 
close(fh); 
return 0; 

/•k , k1<‘k-k-k‘k-k1<‘k-k-k-k-k-k-k'k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k-k‘k-kic-k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k 

The output should: 

Successfully created sample.dat. 

} 

• “chmod — Change File Permission Setting” on page 90 

• “close — Close File Associated with Flandle” on page 99 

• “open — Open File” on page 447 

• “fdopen — Associates Input Or Output With File” on page 219 

• “_sopen — Open Shared File” on page 545 

• “umask — Sets File Mask of Current Process” on page 719 

• “<sys\stat.h>” on page 819 

• “<io.h>” on page 804 
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crotl - crotr — Rotate Bits of Character Value 

Format linclude <stdlib.h> /* also in <builtin.h> */ 

unsigned char _crotl(unsigned char value, int shift); 
unsigned char _crotr(unsigned char value, int shift); 

Description Language Level: Extension 

The _crotl and _crotr functions rotate the character value by shift bits. The 
_crotl function rotates to the left, and _crotr to the right. 

Note: Both _crotl and _crotr are built-in functions, which means they are 
implemented as inline instructions and have no backing code in the library. For this 
reason: 

• You cannot take the address of these functions. 

• You cannot parenthesize a call to either function. (Parentheses specify a call to 
the function's backing code, and these functions have none.) 

Return Value Both functions return the rotated value. There is no error return value. 

This example uses _crotl and _crotr with different shift values to rotate the 
character value: 

#inc1ude <stdio.h> 

#inc1ude <stdlib.h> 

int main(void) 

{ 

unsigned char val = 0X01; 

printf("The value of 0x%2.2x rotated 4 bits to the left is 0x%2.2x\n", val, 

_crotl (val, 4)); 

printf("The value of 0x%2.2x rotated 2 bits to the right is 0x%2.2x\n", 
val, _crotr(val, 2)); 
return 0; 

/**************************************************************************** 

The output should be: 

The value of 0x01 rotated 4 bits to the left is 0x10 
The value of 0x01 rotated 2 bits to the right is 0x40 
****************************************************************************/ 

} 

• “_1 rotl - _1 rotr — Rotate Bits of Unsigned Long Value” on page 392 

• “_rotl - _rotr — Rotate Bits of Unsigned Integer” on page 514 

• “_srotl - _srotr — Rotate Bits of Unsigned Short Value” on page 558 

• “<stdlib.h>” on page 816 

• “<builtin.h>” on page 801 
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_CRT_init 

_CRT_init 

Format 

Description 


Return Value 


Initialize DLL Runtime Environment 

int _CRT_init(void); 

/* no header file - defined in the runtime startup code */ 

Language Level: Extension 

_C RT_i nit initializes the VisualAge C++ runtime environment for a DLL. 

By default, all DLLs call the VisualAge C++ _DLL_InitTerm function, which in turn 
calls _CRT_init for you. However, if you are writing your own _DLL_InitTerm 
function (for example, to perform actions other than runtime initialization and 
termination), you must call _CRT_i ni t from your version of _DLL_Ini tTerm before 
you can call any other runtime functions. 

If your DLL contains C++ code, you must also call _ ctordtorlni t after _CRT_init 

to ensure that static constructors and destructors are initialized properly. 

_ctordtorlnit is defined in the runtime startup code as: 

void _ctordtorlnit(void); 

Note: If you are providing your own version of the _matherr function to be used in 
your DLL, you must also call the _excepti on_dl 1 init function after the 
runtime environment is initialized. Calling this function ensures that the 
proper _matherr function will be called during exception handling. 
_exception_dllinit is defined in the runtime startup code as: 

void _0ptlink _exception_dl1 init( int (*)(struct exception *) ); 

The parameter required is the address of your _matherr function. 

If the runtime environment is successfully initialized, _CRT_init returns 0. A 
return code of -1 indicates an error. If an error occurs, an error message is written to 
file handle 2, which is the usual destination of stderr. 
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This example shows the _DLL_Ini tTerm function from the VisualAge C++ sample 
program for building DLLs, which calls _CRT_i nit to initialize the library 
environment. 

Idefine INCL_DOSMODULEMGR 
Idefine INCL_DOSPROCESS 
#inc1ude <os2.h> 

#include <stdlib.h> 
linclude <stdio.h> 

#include <string.h> 

/* _CRT_init is the C run-time environment initialization function. */ 

/* It will return 0 to indicate success and -1 to indicate failure. */ 

int _CRT_init(void); 

#ifdef STATIC_LINK 

/* _CRT_term is the C run-time environment termination function. */ 

/* It only needs to be called when the C run-time functions are statically */ 

/* linked. */ 

void _CRT_term(void); 

#el se 

/* A clean up routine registered with DosExitList must be used if runtime */ 

/* calls are required and the runtime is dynamically linked. This will */ 

/* guarantee that this clean up routine is run before the library DLL is */ 

/* terminated. */ 

static void _System cleanup(ULONG ulReason); 

#endi f 

size_t nSize; 
int *pArray; 

/* _DLL_InitTerm is the function that gets called by the operating system */ 

/* loader when it loads and frees this DLL for each process that accesses */ 

/* this DLL. However, it only gets called the first time the DLL is loaded */ 

/* and the last time it is freed for a particular process. The system */ 

/* linkage convention MUST be used because the operating system loader is */ 

/* calling this function. */ 

unsigned long _System _DLL_InitTerm(unsigned long hModule, unsigned long 

ul FI ag) 

{ 

size_t i; 

APIRET rc; 

char namebuf[CCHMAXPATH]; 
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/* If ulFlag is zero then the DLL is being loaded so initialization should*/ 
/* be performed. If ulFlag is 1 then the DLL is being freed so */ 

/* termination should be performed. */ 

switch (ulFlag) { 
case 0 : 

/•kic-kle-k-k-k-k-k'k-k-k-k-k-k'k-kick-k-klck-k'k-k-k'k-k-k'k-k-k-k-k-k-k-kick-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-kick-k-k-k-kick-k-klc/ 

/* The C run-time environment initialization function must be */ 

/* called before any calls to C run-time functions that are not */ 

/* inlined. */ 

/•kit-kle-kic-k-klt'k-k-kle-k-kle-k-k'k-k-k'k'k-k'k-k-klck-klckick-k-k'k-k-klck-klck-k-k-k-k'k-k-k'k-kick-k-k'k-k-k'k-k-k'k-k-kle/ 

if (_CRT_init() == -1) 
return OUL; 

#ifndef STATIC LINK 


/•k-k-k'k-k-k-k-k-k-k-k-k'k'k-k-k-k-k'k-k-k-k-k-k'k-kit'k-k-k-k-k-k-k-k-k'k-kick-k-k-k-k-klck-k'k-kick-k-k'k-kick-k-k'k-k-k-k-k-k-k/ 

/* A DosExitList routine must be used to clean up if runtime calls */ 
/* are required and the runtime is dynamically linked. */ 

/•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k1ck-k‘k-k-k‘k-k-k‘k-k-k‘k/ 


if (rc = DosExitList(0X0O0OFF0O|EXLST_ADD, cleanup)) 
printf("DosExitList returned %lu\n", rc); 

#endif 

if (rc = DosQueryModuleName(hModule, CCHMAXPATH, namebuf)) 
printf("DosQueryModuleName returned %lu\n", rc); 
el se 

printf("The name of this DLL is %s\n", namebuf); 
srand(17); 

nSize = (rand()%128)+32; 

printf("The array size for this process is %u\n", nSize); 
if ((pArray = malloc(nSize *sizeof(int))) == NULL) { 

printf("Could not allocate space for unsorted array.\n"); 
return OUL; 


for (i = 0; i < nSize; ++i) 
pArray [i] = rand(); 
break; 
case 1 : 

#ifdef STATIC_LINK 

printf("The array will now be freed.\n"); 
free(pArray); 

_CRT_term(); 

#endif 

break; 
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default : 

printf("ulFIag = %lu\n", ulFlag); 
return OUL; 


/* A non-zero value must be returned to indicate success. */ 

return 1UL; 

} 

#ifndef STATIC_LINK 

static void cleanup(ULONG ulReason) 

{ 

if (!ulReason) { 

printf("The array will now be freed.\n"); 
free(pArray); 

} 

DosExitList(EXLST_EXIT, cleanup); 
return ; 

} 

#endi f 


• Building Dynamic Link Libraries in the Programming Guide 

• “_CRT_term — Terminate DLL Runtime Environment” on page 122 

• “_DLL_Ini tTerm — Initialize and Terminate DLL Environment” on page 170 

• “_rmem_init — Initialize Memory Functions for Subsystem DLL” on page 501 

• “_rmem_term — Terminate Memory Functions for Subsystem DLL” on page 507 

• “_tmem_init — Initialize Memory Functions for Subsystem DLL” on page 669 

• “_tmem_term — Terminate Memory Functions for Subsystem DLL” on page 670 
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_CRT_term 

Format 

Description 


Return Value 



Terminate DLL Runtime Environment 

void _CRT_term(void); 

/* no header file - defined in runtime startup code */ 

Language Level: Extension 

_CRT_term terminates the VisualAge C++ runtime environment. It is only needed for 
DLLs where the C runtime functions are statically linked. 

By default, all DLLs call the VisualAge C++ _DLL_InitTerm function, which in turn 
calls _CRT_term for you. However, if you are writing your own _DLL_Ini tTerm 
function (for example, to perform actions other than runtime initialization and 
termination), and your DLL statically links to the C runtime libraries, you need to call 
_CRT_term from your _DLL_Ini tTerm function. 

If your DLL contains C++ code, you must also call _ctordtorTerm before you call 

_CRT_term to ensure that static constructors and destructors are terminated correctly. 
_ctordtorTerm is defined in the runtime startup code as: 

void _ctordtorTerm(void); 

Once you have called _CRT_term, you cannot call any other library functions. 

If your DLL is dynamically linked, you cannot call library functions in the 
termination section of your _DLL_Ini tTerm function. If your termination routine 
requires calling library functions, you must register the termination routine with 
DosExitList. Note that all DosExitList routines are called before DLL termination 
routines. 

There is no return value for _CRT_term. 

This example shows the _DLL_Ini tTerm function from the VisualAge C++ sample 
program for building DLLs, which calls _CRT_term to terminate the library 
environment. 
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Idefine INCL_DOSMODULEMGR 
Idefine INCL_DOSPROCESS 
#include <os2.h> 

#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

/* _CRT_init is the C run-time environment initialization function. */ 

/* It will return 0 to indicate success and -1 to indicate failure. */ 

int _CRT_init(void); 
lifdef STATIC_LINK 

/* _CRT_term is the C run-time environment termination function. */ 

/* It only needs to be called when the C run-time functions are statically */ 

/* linked. */ 

void _CRT_term(void); 

#el se 

/* A clean up routine registered with DosExitList must be used if runtime */ 

/* calls are required and the runtime is dynamically linked. This will */ 

/* guarantee that this clean up routine is run before the library DLL is */ 

/* terminated. */ 

static void _System cleanup(ULONG ulReason); 

#endi f 

size_t nSize; 
int *pArray; 

/* _DLL_InitTerm is the function that gets called by the operating system */ 

/* loader when it loads and frees this DLL for each process that accesses */ 

/* this DLL. However, it only gets called the first time the DLL is loaded */ 

/* and the last time it is freed for a particular process. The system */ 

/* linkage convention MUST be used because the operating system loader is */ 

/* calling this function. */ 

unsigned long _System _DLL_InitTerm(unsigned long hModule, unsigned long 

ul FI ag) 

{ 

size_t i; 

APIRET rc; 

char namebuf[CCHMAXPATH]; 
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/* If ulFlag is zero then the DLL is being loaded so initialization should*/ 
/* be performed. If ulFlag is 1 then the DLL is being freed so */ 

/* termination should be performed. */ 

switch (ulFlag) { 
case 0 : 

/•kic-kle-k-k-k-k-k'k-k-k-k-k-k'k-kick-k-klck-k'k-k-k'k-k-k'k-k-k-k-k-k-k-kick-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-kick-k-k-k-kick-k-klc/ 

/* The C run-time environment initialization function must be */ 

/* called before any calls to C run-time functions that are not */ 

/* inlined. */ 

/•kit-kle-kic-k-klt'k-k-kle-k-kle-k-k'k-k-k'k'k-k'k-k-klck-klckick-k-k'k-k-klck-klck-k-k-k-k'k-k-k'k-kick-k-k'k-k-k'k-k-k'k-k-kle/ 

if (_CRT_init() == -1) 
return OUL; 

#ifndef STATIC LINK 


/•k-k-k'k-k-k-k-k-k-k-k-k'k'k-k-k-k-k'k-k-k-k-k-k'k-kit'k-k-k-k-k-k-k-k-k'k-kick-k-k-k-k-klck-k'k-kick-k-k'k-kick-k-k'k-k-k-k-k-k-k/ 

/* A DosExitList routine must be used to clean up if runtime calls */ 
/* are required and the runtime is dynamically linked. */ 

/•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k1ck-k‘k-k-k‘k-k-k‘k-k-k‘k/ 


if (rc = DosExitList(0X0O0OFF0O|EXLST_ADD, cleanup)) 
printf("DosExitList returned %lu\n", rc); 

#endif 

if (rc = DosQueryModuleName(hModule, CCHMAXPATH, namebuf)) 
printf("DosQueryModuleName returned %lu\n", rc); 
el se 

printf("The name of this DLL is %s\n", namebuf); 
srand(17); 

nSize = (rand()%128)+32; 

printf("The array size for this process is %u\n", nSize); 
if ((pArray = malloc(nSize *sizeof(int))) == NULL) { 

printf("Could not allocate space for unsorted array.\n"); 
return OUL; 


for (i = 0; i < nSize; ++i) 
pArray [i] = rand(); 
break; 
case 1 : 

#ifdef STATIC_LINK 

printf("The array will now be freed.\n"); 
free(pArray); 

_CRT_term(); 

#endif 

break; 


124 VisualAge C++ C Library Reference 



CRT_term 


default : 

printf("ulFIag = %lu\n", ulFlag); 
return OUL; 


/* A non-zero value must be returned to indicate success. */ 

return 1UL; 

} 

#ifndef STATIC_LINK 

static void cleanup(ULONG ulReason) 

{ 

if (!ulReason) { 

printf("The array will now be freed.\n"); 
free(pArray); 

} 

DosExitList(EXLST_EXIT, cleanup); 
return ; 

} 

#endi f 


• Building Dynamic Link Libraries in the Programming Guide 

• “_CRT_init — Initialize DLL Runtime Environment” on page 118 

• “_DLL_Ini tTerm — Initialize and Terminate DLL Environment” on page 170 

• “_rmem_init — Initialize Memory Functions for Subsystem DLL” on page 501 

• “_rmem_term — Terminate Memory Functions for Subsystem DLL” on page 507 

• “_tmem_init — Initialize Memory Functions for Subsystem DLL” on page 669 

• “_tmem_term — Terminate Memory Functions for Subsystem DLL” on page 670 
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csid — Determine Character Set ID for Multibyte Character 

Format linclude <stdlib.h> 

int csid(const char *c); 

Description Language Level: Extension 

csid queries the locale and determines the character-set identifier for the specified 
character c. 

Return Value csid returns the character-set identifier, or -1 if the character is not valid. 

This example checks the character-set ID for a character. 

linclude <locale.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

char *string = "A"; 
int rc; 

rc = csid(string); 

printf("character 1 %s' is in character set id %i\n", string, rc); 
return 0; 

/************************************************************'**'*'*****'***'*'**'** 

The output should be similar to : 

character 'A' is in character set id 0 

■k-k-k-kle-k'k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-kick-k'k j 

} 

• “wcsid — Determine Character Set ID for Wide Character” on page 762 

• “<stdlib.h>” on page 816 
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cscanf — Read Data from Keyboard 

Format linclude <conio.h> 

int _cscanf(char *format-string, argument-list) ; 

Description Language Level: Extension 

_cscanf reads data directly from the keyboard to the locations given by 
argument-list , if any are specified. The _cscanf function uses the _getche 
function to read characters. Each argument must be a pointer to a variable with a 
type that corresponds to a type specifier in the format-string. 

The format-string controls the interpretation of the input fields and has the same 
form and function as the format-string argument for the scanf function. See 
“scanf — Read Data” on page 517 for a description of the format-string. 

Note: Although _cscanf normally echoes the input character, it does not do so if 
the last action was a call to _ungetch. 

Return Value _cscanf returns the number of fields that were successfully converted and assigned. 
The return value does not include fields that were read but not assigned. 

The return value is EOF for an attempt to read at the end of the file. A return value 
of 0 means that no fields were assigned. 

This example uses _cscanf to read strings from the screen. 

#inc1ude <conio.h> 

int main(void) 

{ 

char buffer[24]; 

_cprintf("\nPlease enter a filename:\n"); 

_cscanf("%23s", buffer); 

_cprintf("\nThe file name you entered was %23s.", buffer); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

Please enter a filename: 

file.dat 

The filename you entered was file.dat. 

****************************************************************************/ 

} 

• “fscanf — Read Formatted Data” on page 271 

• “_getch - _getche — Read Character from Keyboard” on page 298 

• “scanf — Read Data” on page 517 
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• “sscanf — Read Data” on page 559 

• “_ungetch — Push Character Back to Keyboard” on page 723 

• “<conio.h>” on page 802 
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ctime — Convert Time to Character String 

Format linclude <time.h> 

char *ctime(const time_t *time ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

ctime converts the time value pointed to by time to local time in the form of a 
character string. A time value is usually obtained by a call to the time function. 

The string result produced by ctime contains exactly 26 characters and has the format: 

"%.3s %.3s%3d %.2d:%.2d:%.2d %d\n" 

For example: 

Mon Jul 16 02:03:55 1987\n\0 

ctime uses a 24-hour clock format. The days are abbreviated to: Sun, Mon, Tue, Wed, 
Thu, Fri, and Sat. The months are abbreviated to: Jan, Feb, Mar, Apr, May, Jun, Jul, 
Aug, Sep, Oct, Nov, and Dec. All fields have a constant width. Dates with only one 
digit are preceded with a blank space. The new-line character (\n) and the null 
character (\0) occupy the last two positions of the string. 

The time and date functions begin at 00:00:00 Universal Time, January 1, 1970. 


Return Value ctime returns a pointer to the character string result. There is no error return value. 
A call to ctime is equivalent to: 

asctime(localtime(&anytime)) 

Note: The asctime, ctime, and other time functions may use a common, statically 
allocated buffer for holding the return string. Each call to one of these 
functions may destroy the result of the previous call. 



This example polls the system clock using ctime. It then prints a message giving the 
current date and time. 
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#include <time.h> 
#include <stdio.h> 


int main(void) 

{ 

time_t Itime; 
time(&ltime); 

printf("The time is %s", ctime(&ltime)); 
return 0; 

/**************************************************************************** 

The output should be similar to : 


The time is Thu Dec 15 18:10:23 1994 

****************************************************************************/ 



“asctime — Convert Time to Character String” on page 55 
“gmtime — Convert Time” on page 321 
“localtime — Convert Time” on page 385 
“mktime — Convert Local Time” on page 438 
“strftime — Convert to Formatted Time” on page 586 
“t i me — Determine Current Time” on page 666 
“<time.h>” on page 819 
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cwait — Wait for Child Process 

Format linclude <process.h> 

int _cwait(int *stat_loc, int processed , int action_code ); 

Description Language Level: Extension 

_cwait delays the completion of a parent process until the child process specified by 
processed ends. 

The processed is the value returned by the _spawn function that started the child 
process. If the specified child process ends before _cwait is called, _cwait returns 
to the calling process immediately with a value of -1. If the value of process_id is 
0, the parent process waits until all of its child processes end. 

If the variable pointed to by stat_loc is NULL, _cwait does not use it. If it is not 
NULL, _cwait places information about the return status and the return code of the 
child process in the location pointed to by stat_loc. 

If the child process ended normally with a call to the OS/2 DosExit API, the 
lowest-order byte of the variable pointed to by stat_loc is 0. The next 
highest-order byte contains the lowest-order byte of the argument passed to DosExit 
by the child process. The value of this byte depends on how the child process caused 
the system to call DosExit. If the child called exit, _exit, or return from main, or 
used a DosExit coded into the program, the byte contains the lowest-order byte of the 
argument the child passed to exi t, _exi t, or return. The value of the byte is 
undefined if the child caused a DosExit call simply by reaching the end of main. 

If the child process ended abnormally (without a call to DosExit), the lowest-order 
byte of the variable pointed to by stat_loc contains the return code from the OS/2 
DosWaitChild API, and the next higher-order byte is 0. See the OS/2 online reference 
for details about the DosWaitChild return codes. 

The action_code specifies when the parent process is to start running again. Values 
for action_code include: 

Action Code Meaning 

WAIT_CHILD The parent process waits until the specified child process 

ends. 

WAIT_GRANDCHILD The parent process waits until the child process and all of 
the child processes of that process end. 

The action code values are defined in <process.h>. 
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Return Value 



Note: Because the size of an int is only 2 bytes in 16-bit compilers, if you are 
migrating a 16-bit program, some parts of your programs may have to be rewritten if 
they use this function. 

An alternative to this function is the DosWaitChild API call. 

At the normal end of the child process, _cwait returns the process identifier of the 
child to the parent process. If a child process ends abnormally, _cwait returns -1 to 
the parent process and sets errno to EINTR. In the case of an error, _cwait returns 
immediately with a value of -1 and sets errno to one of the following values: 

Value Meaning 
EINVAL Incorrect action code. 

ECHILD No child process exists, or the process identifier is incorrect. 

This example creates a new process called child.exe. The parent calls _cwait and 
waits for the child to end. The parent then displays the child's return information in 
hexadecimal. 

#include <stdio.h> 
linclude <process.h> 

#include <errno.h> 

int stat_child; 

int main(void) 

{ 

int i.result; 

/* spawn a child and 'cwait' for it to finish */ 

if ((result = _spawnl(P_N0WAIT, "child", "child", "1", NULL)) != -1) { 
if ((i = _cwait(&stat_chi1d, result, WAIT_CHILD)) != result) 
printf("Error ...expected pid from child"); 
else { 

if (0 == errno) { 

printf("Chi 1d process ended successfully and ...\n"); 
printf("program returned to the Parent process.\n"); 

} 

el se 

printf("Chi 1d process had an error\n"); 


else 

printf("Error ...could not spawn a child process\n"); 
return 0; 
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/**************************************************************************** 
If the source code for child.exe is: 

#inc1ude <stdio.h> 
int main(void) { 

puts("This line was written by child.exe"); 
return 0; 

} 


The output should be similar to : 

This line was written by child.exe 
Child process ended successfully and ... 
program returned to the Parent process. 
****************************************************************************/ 


• “exi t — End Program” on page 204 

• “_exit — End Process” on page 205 

• “_spawnl - _spawnvpe — Start and Run Child Processes” on page 548 

• return 

• “<process.h>” on page 812 
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_cxchg — Exchange Character Value with Memory 

Format linclude <builtin.h> 

signed char _Builtin _cxchg(volati1e signed char *lockptr, 

signed char value ); 


Description Language Level: Extension 

_cxchg puts the specified value in the memory location pointed to by lockptr , and 

returns the value that was previously in that location. 

Use this function to implement fast-RAM semaphores to serialize access to a critical 
resource (so that only one thread can use it at a time). You can also use OS/2 
semaphores to serialize resource access, but they are slower. Typically you would 
create both a fast-RAM semaphore and an OS/2 semaphore for the resource. For 
more details about OS/2 semaphores and how to use them, see the Control Program 
Guide and Reference. 

To implement a fast-RAM semaphore, allocate a volatile memory location (for 

_cxchg, it must be a signed char), and statically initialize it to 0 to indicate that the 

resource is free (not being used). To give a thread access to the resource, call 

_cxchg from the thread to exchange a nonzero value with that memory location. If 

_cxchg returns 0, the thread can access the resource; it has also set the memory 

location so that other threads can tell the resource is in use. When your thread no 
longer needs the resource, call_cxchg again to reset the memory location to 0. 

If_cxchg returns a nonzero value, another thread is already using the resource, and 

the calling thread must wait for access. You could then use the OS/2 semaphore to 
inform your waiting thread when the resource is unlocked by the thread currently 
using it. 

It is important that you set the memory to a nonzero value when you are using the 
resource. You can use the same nonzero value for all threads, or a unique value for 
each. 

Note: _cxchg is a built-in function, which means it is implemented as an inline 

instruction and has no backing code in the library. For this reason: 

• You cannot take the address of_cxchg. 

• You cannot parenthesize a call to_cxchg. (Parentheses specify a call to the 

function's backing code, and_cxchg has none.) 
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Return Value 



_cxchg returns the previous value stored in the memory location pointed to by 

lockptr. 

This example creates five separate threads, each associated with a State. At most 
two threads can have a State of Eating at the same time. When a thread calls 
PickUpChopSticks, that function checks the states of the preceding threads to make 

sure they are not already Eating, If the call to_cxchg is successful, the thread has 

locked the Lock semaphore and can change its State to Eating. It then calls_cxchg 

a second time to unlock the semaphore, and returns. 

If_cxchg cannot lock the semaphore, another thread has it locked. The current 

thread then suspends itself briefly with DosSleep and Uies again. The semaphore is 
used to ensure that two threads cannot simultaneously change their State to Eating, 
which would cause a deadlock. (Note that although the semaphore solves the 
problem of deadlock, it is not an optimal solution; some threads may never get the 
semaphore or the State of Eating.) 

Note: You must compile this example with the multithread (/Gm) option. The 
example runs in an infinite loop; press Ctrl-C to end it. 

Ipragma strings(readonly) 

Idefine INCL_D0S 
#include <os2.h> 

#inc1ude <stdlib.h> 

#include <stdio.h> 

#include <builtin.h> 

typedef enum { 

Thinking, 

Eating. 

Hungry 
} States; 

Idefine UNLOCKED 0 
Idefine LOCKED 1 
Idefine NUM PHILOSOPHERS 5 
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static volatile signed char Lock; 
static States State[NUM_PHILOSOPHERS]; 

static const int NameMap[NUM_PHILOSOPHERS] = {0, 1, 2, 3, 4}; 
static const char * const Names[NUM_PHILOSOPHERS] = {"Plato", 

"Socrates", 
"Kant", 
"Hegel", 
"Nietsche"}; 


void PickUpChopSticks(int Ident); 
void PutDownChopSticks(int Ident); 
void Think(int Ident); 
void Eat(int Ident); 

void _0ptlink StartPhi1osopher(void *pldent); 

void _0ptlink StartPhi1osopher(void *pldent) 

{ 

int Ident = *{int *)pldent; 
while (1) { 

State[Ident] - Hungry; 

printf("%s hungry.\n". Names[Ident]); 

PickUpChopSticks(Ident); 

Eat(Ident); 

PutDownChopSticks(Ident); 

Think(Ident); 



int main(int argc, char *argv[], char *envp[]) 

{ 

int i; 

unsigned long tid; 

for (i =0; i < NUM_PHIL0S0PHERS; i++) { 

tid = _beginthread(StartPhilosopher, NULL, 8192, (void *)&NameMap[i]); 
if (tid == -1) { 

printf("Unable to start %s.\n", Names[i]); 

} 

else { 

printf("%s started with Thread Id = %d.\n“, Names[i], tid); 


DosWaitThread(&tid, DCWW_WAIT); 
return 0; 
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void PickUpChopSticks(int Ident) 

{ 

while (1) { 

if (State[(Ident + NUM_PHILOSOPHERS - 1) % NUM_PHILOSOPHERS] != Eating && 
State [(Ident + 1) % NUM_PHILOSOPHERS] != Eating && 

!_cxchg(&Lock, LOCKED)) { 

State[Ident] = Eating; 

_cxchg(&Lock, UNLOCKED); 

return; 


el se { 

DosSleep(l); 

} 

} 

} 


void PutDownChopSticks(int Ident) 

{ 

State[Ident] = Thinking; 

} 

void Eat(int Ident) 

{ 

printf("%s eating.\n". Names[Ident]); 
DosSleep(l); 


void Think(int Ident) 

{ 

printf("%s thinking.\n". Names[Ident]); 
DosSleep(l); 


/**************************************************************************** 
The output should be similar to : 

Plato started with Thread Id = 2. 

Socrates started with Thread Id = 3. 

Kant started with Thread Id = 4. 

Hegel started with Thread Id = 5. 

Nietsche started with Thread Id = 6. 

Plato hungry. 

Plato eating. 

Socrates hungry. 

Kant hungry. 

Kant eating. 

Hegel hungry. 

Nietsche hungry. 

Kant thinking. 
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Plato thinking. 

Plato hungry. 

Plato eating. 

Kant hungry. 

Kant eating. 

****************************************************************************/ 



“ lxchg — Exchange Integer Value with Memory” on page 397 

“ sxchg — Exchange Integer Value with Memory” on page 641 

“<builtin.h>” on page 801 
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debug calloc — Allocate and Initialize Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *_debug_calloc(size_t num, size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

_debug_cal 1 oc is the debug version of cal 1 oc. Like cal 1 oc, it allocates memory 
from the default heap for an array of num elements, each of length size bytes. It 
then initializes all bits of each element to 0. 

In addition, _debug_cal loc makes an implicit call to _heap_check, and stores the 
name of the file fi le and the line number l ine where the storage is allocated. This 
information can be used later by the _heap_check and _dump_al located or 
_dump_al 1 ocated_del ta functions. 

To use _debug_cal loc, you must compile with the debug memory (/Tm) compiler 
option. This option maps all cal loc calls to _debug_cal loc (you can also call 
_debug_cal 1 oc explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

To reallocate or free memory allocated by _debug_cal 1 oc, use _debug_real 1 oc and 
_debug_free; you can also use realloc and free if you do not want debug 
information about the operation. 

Heap-specific and tiled versions of this function (_debug_ucal 1 oc and 
_debug_tcal loc) are also available. _debug_cal loc always allocates memory from 
the default heap. 

Return Value _debug_cal 1 oc returns a pointer to the reserved space. If not enough memory is 
available, or if num or size is 0, _debug_cal loc returns NULL. 
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debug_calloc 



This example reserves storage of 100 bytes. It then attempts to write to storage that 
was not allocated. When _debug_cal loc is called again, _heap_check detects the 
error, generates several messages, and stops the program. 


Note: You must compile this example with the /Tm option to map the cal 1 oc calls 
to _debug_cal 1 oc. 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


int main(void) 

{ 

char *ptrl, *ptr2; 


if (NULL == (ptrl = calloc(l, 100))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptrl, 'a', 105); /* overwrites storage that was not allocated */ 

ptr2 = calloc(2, 20); /* this call to calloc invokes _heap_check */ 

puts("_debug_calloc did not detect that a memory block was overwritten."); 
return 0; 


/**************************************************************************** 

The output should be similar to: 

End of allocated object 0x00073890 was overwritten at 0xQ00738f4. 

The first eight bytes of the memory block (in hex) are: 6161616161616161. 
This memory block was (re)al1ocated at line number 9 in _debug_cal1o.c. 
Heap state was valid at line 9 of _debug_cal1o.c. 

Memory error detected at line 14 of _debug_callo.c. 
****************************************************************************/ 

} 



Memory Management in the Programming Guide 
Debugging Your Heaps in the Programming Guide 
“Differentiating between Memory Management Functions” on page 28 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 

“cal loc — Reserve and Initialize Storage” on page 80 
“_debug_ucal loc — Reserve and Initialize Memory from User Heap” on 
page 160 

“_debug_free — Release Memory” on page 141 

“_debug_mal 1 oc — Allocate Memory” on page 145 

“_debug_real 1 oc — Reallocate Memory Block” on page 147 

“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 

“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 

page 183 

“_heap_check — Validate Default Memory Heap” on page 323 
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debug_free 


_debug_free 

Format 

Description 


Return Value 



— Release Memory 

linclude <stdlib.h> /* also in <malloc.h> */ 
void _debug_free(void *ptr, const char *file, 

size_t line); 

Language Level: Extension 

_debug_free is the debug version of free. Like free, it frees the block of memory 
pointed to by ptr. _debug_free also sets each block of freed memory to 0xFB, so 
you can easily locate instances where your program uses the data in freed memory. 

In addition, _debug_free makes an implicit call to the _heap_check, and stores the 
file name fi le and the line number l ine where the memory is freed. This 
information can be used later by the _heap_check and _dump_al located or 
_dump_al 1 ocated_del ta functions. 

To use _debug_free, you must compile with the debug memory (/Tm) compiler 
option. This option maps all free calls to _debug_free (you can also call 
_debug_free explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Because _debug_free always checks what heap the memory was allocated from, you 
can use _debug_free to free memory blocks allocated by the regular, tiled, 
heap-specific, or debug versions of the memory management functions. However, if 
the memory was not allocated by the memory management functions, or was 
previously freed, _debug_free generates an error message and the program ends. 

A tiled version of this function, _debug_tfree, is also available. 

There is no return value. 

This example reserves two blocks, one of 10 bytes and the other of 20 bytes. It then 
frees the first block and attempts to overwrite the freed storage. When _debug_free 
is called a second time, _heap_check detects the error, prints out several messages, 
and stops the program. 

Note: You must compile this example with the /Tm option to map the free calls to 
_debug_free. 
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debug_free 


#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *ptrl, *ptr2; 

if (NULL == (ptrl = malloc(10)) || NULL == (ptr2 = malloc(20))) { 
puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

free(ptrl); 

memset(ptrl, 'a', 5); /* overwrites storage that has been freed */ 

free(ptr2); /* this call to free invokes _heap_check */ 

puts("_debug_free did not detect that a freed memory block was overwritten."); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

Free heap was overwritten at 0x00073890. 

Heap state was valid at line 12 of _debug_free.c. 

Memory error detected at line 14 of _debug_free.c. 
****************************************************************************/ 



Memory Management in the Programming Guide 
Debugging Your Heaps in the Programming Guide 
“Differentiating between Memory Management Functions” on page 28 
“_debug_cal loc — Allocate and Initialize Memory” on page 139 
“_debug_mal 1 oc — Allocate Memory” on page 145 
“_debug_real 1 oc — Reallocate Memory Block” on page 147 
“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“free — Release Storage Blocks” on page 263 
“_heap_check — Validate Default Memory Heap” on page 323 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug_heapmin 


debug heapmin — Release Unused Memory in the Default Heap 

Format linclude <std1ib.h> /* also in <malloc.h> */ 

int _debug_heapmin(const char *file, size_t line); 

Description Language Level: Extension 

_debug_heapmi n is the debug version of _heapmi n. Like _heapmi n. It returns all 
unused memory from the default runtime heap to the operating system. 

In addition, _debug_heapmi n makes an implicit call to _heap_check, and stores the 
file name fi le and the line number l ine where the memory is returned. This 
information can be used later by the _heap_check function. 

To use _debug_heapmi n, you must compile with the debug memory (/Tm) compiler 
option. This option maps all _heapmin calls to _debug_heapmin (you can also call 
_debug_heapmi n explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Heap-specific and tiled versions of this function (_debug_uheapmi n and 
_debug_theapmin) are also available. _debug_heapmi n always operates on the 
default heap. 


Return Value If successful, _debug_heapmi n returns 0; otherwise, it returns -1. 



This example allocates 10000 bytes of storage, changes the storage size to 10 bytes, 
and then uses _debug_heapmi n to return the unused memory to the operating system. 
The program then attempts to overwrite memory that was not allocated. When 
_debug_heapmin is called again, _heap_check detects the error, generates several 
messages, and stops the program. 

Note: You must compile this example with the /Tm option to map the _heapmin 
calls to _debug_heapmin. 
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debug_heapmin 


#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *ptr; 

/* Allocate a large object from the system */ 
if (NULL == (ptr = malloc(10O0OO))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

ptr = real 1oc(ptr, 10); 


heapmin(); 

/* 

No allocation problems 

to detect 

*/ 

*(ptr - 1) = 1 a'; 

/* 

Overwrite memory that 

was not allocated 

*/ 

heapmin(); 

/* 

This call to heapmin 

invokes heap check 

*/ 


puts("_debug_heapmin did not detect that a non-al1ocated memory block" 

"was overwritten."); 
return 0; 

/**************************************************************************** 

Possible output is: 

Header information of object 0xO0O738bO was overwritten at 0x000738ac. 

The first eight bytes of the memory block (in hex) are: AAAAAAAAAAAAAAAA. 
This memory block was (re)allocated at line number 13 in _debug_heapm.c. 
Heap state was valid at line 14 of _debug_heapm.c. 

Memory error detected at line 17 of _debug_heapm.c. 
****************************************************************************/ 



Memory Management in the Programming Guide 
Debugging Your Heaps in the Programming Guide 
“Differentiating between Memory Management Functions” on page 28 
“_debug_heapmi n — Release Unused Memory in the Default Heap” on 
page 143 

“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_heapmin — Release Unused Memory from Default Heap” on page 327 
“_heap_check — Validate Default Memory Heap” on page 323 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug_malloe 


debug mal 1 oc — Allocate Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *_debug_malloc(size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

_debug_mal 1 oc is the debug version of mal 1 oc. Like mal 1 oc, it reserves a block of 
storage of size bytes from the default heap. _debug_mal 1 oc also sets all the 
memory it allocates to BxAA, so you can easily locate instances where your program 
uses the data in the memory without initializing it first. 

In addition, _debug_mal loc makes an implicit call to _heap_check, and stores the 
file name file and the line number line where the storage is allocated. This 
information can later be used by the _heap_check and _dump_al located or 
_dump_al 1 ocated_del ta functions. 

To use _debug_mal loc, you must compile with the debug memory (/Tm) compiler 
option. This option maps all mal 1 oc calls to _debug_mal 1 oc (you can also call 
_debug_mal 1 oc explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

To reallocate or free memory allocated by _debug_mal 1 oc, use _debug_real 1 oc and 
_debug_free; you can also use realloc and free if you do not want debug 
information about the operation. 

Heap-specific and tiled versions of this function (_debug_umal 1 oc and 
_debug_tmal loc) are also available. _debug_mal loc always allocates memory from 
the default heap. 

Return Value _debug_mal 1 oc returns a pointer to the reserved space. If not enough memory is 
available or if size is 0, _debug_malloc returns NULL. 
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debug_malloc 



This example allocates 100 bytes of storage. It then attempts to write to storage that 
was not allocated. When _debug_mal loc is called again, _heap_check detects the 
error, generates several messages, and stops the program. 

Note: You must compile this example with the /Tm option to map the mal 1 oc calls 
to _debug_mal 1 oc. 

#include <stdlib.h> 

#include <stdio.h> 


int main(void) 

{ 

char *ptrl, *ptr2; 

if (NULL == (ptrl = mal1oc(10Q))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

*(ptrl - 1) = 'a'; /* overwrites storage that was not allocated */ 

ptr2 = mal1oc(10); /* this call to malloc invokes _heap_check */ 

puts("_debug_malloc did not detect that a memory block was overwritten."); 
return 0; 

/**************************************************************************** 

Possible output is: 

Header information of object 0x00073890 was overwritten at 0x0007388c. 

The first eight bytes of the memory block (in hex) are: AAAAAAAAAAAAAAAA. 
This memory block was (re)al1ocated at line number 8 in _debug_mal1o.c. 
Heap state was valid at line 8 of _debug_mal1o.c. 

Memory error detected at line 13 of _debug_mallo.c. 
****************************************************************************/ 



Memory Management in the Programming Guide 
Debugging Your Heaps in the Programming Guide 
“Differentiating between Memory Management Functions” on page 28 
“_debug_cal loc — Allocate and Initialize Memory” on page 139 
“_debug_free — Release Memory” on page 141 
“_debug_real loc — Reallocate Memory Block” on page 147 
“_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 
“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_heap_check — Validate Default Memory Heap” on page 323 
“mal loc — Reserve Storage Block” on page 403 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug_realloe 


debug real 1 oc — Reallocate Memory Block 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *_debug_real loc(void *ptr, size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

_debug_real 1 oc is the debug version of real 1 oc. Like real 1 oc, it reallocates the 
block of memory pointed to by ptr to a new size, specified in bytes. It also sets 
any new memory it allocates to QxAA, so you can easily locate instances where your 
program tries to use the data in that memory without initializing it first. 

In addition, _debug_real 1 oc makes an implicit call to _heap_check, and stores the 
file name file and the line number line where the storage is reallocated. This 
information can be used later by the _heap_check and _dump_al located or 
_dump_al 1 ocated_del ta functions. 

If ptr is NULL, _debug_real 1 oc behaves like _debug_mal 1 oc (or mal 1 oc) and 
allocates the block of memory. 

To use _debug_real loc, you must compile with the debug memory (/Tm) compiler 
option. This option maps all real loc calls to _debug_real loc (you can also call 
_debug_real 1 oc explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Because _debug_real loc always checks what heap the memory was allocated from, 
you can use _debug_real 1 oc to reallocate memory blocks allocated by the regular, 
tiled heap-specific, or debug versions of the memory management functions. 

However, if the memory was not allocated by the memory management functions, or 
was previously freed, _debug_real 1 oc generates an error message and the program 
ends. 

A tiled version of this function, _debug_Lreal 1 oc, is also available. 

Return Value _debug_real loc returns a pointer to the reallocated memory block. The ptr 

argument to _debug_real 1 oc is not the same as the return value; _debug_real 1 oc 
always changes the memory location to help you locate references to the memory that 
were not freed before the memory was reallocated. 
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debug_realloc 


If size is 0, _debug_real loc returns NULL. If not enough memory is available to 
expand the block to the given size, the original block is unchanged and NULL is 
returned. 



This example uses _debug_real loc to allocate 100 bytes of storage. It then attempts 
to write to storage that was not allocated. When _debug_real loc is called again, 
_heap_check detects the error, generates several messages, and stops the program. 

Note: You must compile this example with the /Tm option to map the real loc calls 
to _debug_real 1 oc. 

#include <stdlib.h> 

#include <stdio.h> 


int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = realloc(NULL, 100))) { 
puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'a 1 , 105); /* overwrites storage that was not allocated */ 

ptr = realloc(ptr, 200); /* this call to realloc invokes _heap_check */ 

puts("_debug_realloc did not detect that a memory block was overwritten." ); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

End of allocated object 0x00073890 was overwritten at 0x000738f4. 

The first eight bytes of the memory block (in hex) are: 6161616161616161. 
This memory block was (re)allocated at line number 8 in _debug_real1,c. 
Heap state was valid at line 8 of _debug_real1,c. 

Memory error detected at line 13 of _debug_reall,c. 
****************************************************************************/ 



Memory Management in the Programming Guide 
Debugging Your Heaps in the Programming Guide 
“Differentiating between Memory Management Functions” on page 28 
“_debug_cal loc — Allocate and Initialize Memory” on page 139 
“_debug_free — Release Memory” on page 141 
“_debug_mal 1 oc — Allocate Memory” on page 145 

“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_heap_check — Validate Default Memory Heap” on page 323 
“real loc — Change Reserved Storage Block Size” on page 484 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug_tealloe 


debug tcal 1 oc — Reserve and Initialize Tiled Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *_debug_tcalloc(size_t num, size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

_debug_tcal 1 oc is the debug version of _tcal 1 oc. Like _tcal 1 oc, it allocates tiled 
memory from the tiled runtime heap for an array of num elements, each of length 
size bytes. It then initializes all bits of each element to 0. 

In addition, _debug_tcal 1 oc makes an implicit call to _theap_check, and stores the 
name of the file fi le and the line number l ine where the storage is allocated. This 
information can be used later by the _theap_check and _tdump_al 1 ocated or 
_tdump_al 1 ocated_del ta functions. 

To use _debug_tcal loc, you must compile with the debug memory and tiled 
memory compiler options (/Tm /Gt). These options map all cal loc calls to 
_debug_tcal loc (you can also call _debug_tcal loc explicitly). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

To reallocate or free memory allocated with _debug_tcal 1 oc, use _debug_treal 1 oc 
and _debug_tfree; you can also use _treal loc and _tfree if you don't want debug 
information about the operation. 

_debug_tcal loc works just like _debug_cal loc except that it allocates tiled memory 
instead of regular memory. If you have objects that may be accessed by 16-bit code, 
you should store them in tiled memory. Tiled memory is guaranteed not to cross 64K 
boundaries, as long as the object is less than 64K in size. Objects larger than 64K in 
size are aligned on 64K boundaries, but will also cross 64K boundaries. You can 
also create your own heaps of tiled memory. See “Managing Memory” in the 
Programming Guide for more information. 


Return Value _debug_tcal 1 oc returns a pointer to the reserved space. If size or num was 
specified as zero, _debug_tcal loc returns NULL. 



This example reserves 100 bytes of tiled memory. It then attempts to write to storage 
that was not allocated. The second _debug_tcal loc call invokes _theap_check, 
which detects the error, generates several messages, and stops the program. 
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debug_tcalloc 


Note: You must compile this program with the /Tm /Gt options to map the cal 1 oc 
calls to _debug_tcal 1 oc 

#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

int main(void) 

{ 

char *ptr; 

/* calloc is mapped to _debug_tcalloc */ 
if (NULL == (ptr = ca11oc(l, 100))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

memset (ptr, 'x', 105); /* Overwrites storage that was not allocated */ 

free(ptr); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

End of allocated object 0x00080120 was overwritten at 0x00080184. 

The first eight bytes of the memory block (in hex) are: 7878787878787878. 

This memory block was (re)allocated at line number 10 in _debug_tcallo.c. 

Heap state was valid at line 10 of _debug_tcallo.c. 

Memory error detected at line 15 of _debug_tcallo.c. 
****************************************************************************/ 



“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“Tiled Debug Functions” on page 32 
“cal loc — Reserve and Initialize Storage” on page 80 
“_debug_cal loc — Allocate and Initialize Memory” on page 139 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 
“_tdump_al located — Get Information about Allocated Tiled Memory” on 
page 649 

“_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

“_theap_check — Validate User Memory Heap” on page 661 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug_tfree 


debug tfree — Release Tiled Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void _debug_tfree(void *ptr, const char *file, 
size_t line); 

Description Language Level: Extension 

_debug_tfree is the debug version of _tfree. Like _tfree, it frees the block of 
tiled memory pointed to by ptr. _debug_tfree also sets each block of freed 
memory to OxFB, so you can easily locate instances where your program uses the data 
in freed memory. 

In addition, _debug_tfree makes an implicit call to the _theap_check, and stores 
the file name fi le and the line number line where the memory is freed. This 
information can be used later by the _theap_check and _tdump_al 1 ocated or 
_tdump_al 1 ocated_del ta functions. 

To use _debug_tfree, you must compile with the debug memory and tiled memory 
compiler options (/Tm /Gt). These options map all free calls to _debug_tfree (you 
can also call _debug_tfree explicitly). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

_debug_tfree works just like _debug_free except that it frees tiled memory instead 
of regular memory. If you have objects that may be accessed by 16-bit code, you 
should store them in tiled memory. Tiled memory is guaranteed not to cross 64K 
boundaries, as long as the object is less than 64K in size. Objects larger than 64K in 
size are aligned on 64K boundaries, but will also cross 64K boundaries. You can 
also create your own heaps of tiled memory. See “Managing Memory” in the 
Programming Guide for more information. 


Return Value There is no return value. 



This example allocates a 100-byte block of memory. It then frees the block twice. 
The second _debug_tfree call invokes _theap_check, which detects the error, 
generates several messages, and stops the program. 

Note: You must compile this example with the /Tm /Gt options to map the free 
calls to _debug_tfree. 
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#include <stdlib.h> 
#include <stdio.h> 


int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = mal1oc(100))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

free(ptr); /* free the object */ 

free(ptr); /* free the object again should cause an error */ 

return 0; 


/**************************************************************************** 

The output should be similar to : 

Object 0x00080120 provided is either invalid or was overwritten at 
0x0008011c. 

Memory error detected at line 13 of _debug_tfree.c. 
****************************************************************************/ 

} 



“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“Tiled Debug Functions” on page 32 
“_debug_free — Release Memory” on page 141 

“_debug_tcal loc — Reserve and Initialize Tiled Memory” on page 149 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 
“free — Release Storage Blocks” on page 263 

“_tdump_al located — Get Information about Allocated Tiled Memory” on 
page 649 

“_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

“_tfree — Free Tiled Storage Block” on page 659 
“_theap_check — Validate User Memory Heap” on page 661 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug_theapmin 


debug theapmi n — Release Unused Tiled Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

int _debug_theapmin(const char *file, size_t line); 

Description Language Level: Extension 

_debug_theapmin is the debug version of _theapmin. Like _theapmin, it returns all 
unused blocks of tiled memory to the tiled runtime heap. 

In addition, _debug_theapmi n makes an implicit call to _theap_check to validate the 
heap. 

To use _debug_theapmi n, you must compile with the debug memory and tiled 
memory compiler options (/Tm /Gt). These options map all _heapmin calls to 
_debug_theapmin (you can also call _debug_theapmi n explicitly). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

_debug_theapmin works just like _debug_heapmin except that it releases only 
memory allocated with the tiled memory management functions. 


Return Value If successful, _debug_theapmi n returns 0 . A non-zero return value indicates 

failure. If the heap specified is not valid, _debug_theapmi n generates an error 
message with the file name and line number where the call to _debug_theapmi n was 
made. 



This example allocates 60000 bytes of memory, then frees it. The freed memory is 
kept in the default runtime heap until the call to _debug_theapmi n returns it to the 
operating system. Because no errors are detected by _theap_check, no messages are 
generated. 

Note: You must compile this example with the /Tm /Gt options to map the 
_heapmi n calls to _debug_theapmi n. 
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debug_theapmin 


#include <stdlib.h> 
#include <stdio.h> 


int main(void) 

{ 

char *ptr; 

/* Allocate a large object from the system. */ 
if (NULL == (ptr = malloc(60000))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x 1 , 60000); 

/* The free will keep large object in runtime. */ 
free(ptr); 


/* _debug_theapmin will attempt to return the freed object to the system. */ 
if (0 != _heapmin()) { 

puts("_debug_theapmin returns failed.\n"); 
exit(EXIT_FAILURE); 

} 

return 0; 



“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“Tiled Debug Functions” on page 32 

“_debug_heapmi n — Release Unused Memory in the Default Heap” on 
page 143 

“_debug_tcal loc — Reserve and Initialize Tiled Memory” on page 149 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
“_heapmin — Release Unused Memory from Default Heap” on page 327 
“_theap_check — Validate User Memory Heap” on page 661 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug tmal 1 oc — Reserve Tiled Memory 

Format linclude <std1ib.h> /* also in <malloc.h> */ 

void *_debug_tmalloc(size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

_debug_tmal 1 oc is the debug version of _tmal 1 oc. Like _tmal 1 oc, it allocates tiled 
memory from the tiled runtime heap for an object of length size bytes. 

_debug_tmal loc also sets all the memory it allocates to QxAA, so you can easily 
locate instances where your program uses the data in the memory without initializing 
it first. 

In addition, _debug_tmal 1 oc makes an implicit call to _theap_check, and stores the 
name of the file fi le and the line number l ine where the storage is allocated. This 
information can be used later by the _theap_check and _tdump_al 1 ocated or 
_tdump_al 1 ocated_del ta functions. 

To use _debug_tmal loc, you must compile with the debug memory and tiled 
memory compiler options (/Tm /Gt). These options map all mal loc calls to 
_debug_tmal loc (you can also call _debug_tmal loc explicitly). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

_debug_tmal loc works just like _debug_mal loc except that it allocates tiled memory 
instead of regular memory. If you have objects that may be accessed by 16-bit code, 
you should store them in tiled memory. Tiled memory is guaranteed not to cross 64K 
boundaries, as long as the object is less than 64K in size. Objects larger than 64K in 
size are aligned on 64K boundaries, but will also cross 64K boundaries. You can 
also create your own heaps of tiled memory. See “Managing Memory” in the 
Programming Guide for more information. 

To reallocate or free memory allocated with _debug_tmal 1 oc, use _debug_treal 1 oc 
and _debug_tfree; you can also use _treal loc and _tfree if you don't want debug 
information about the operation. 


Return Value _debug_tmal loc returns a pointer to the reserved space. If size was specified as 
zero, _debug_tmal loc returns NULL. 



This example allocates 100 bytes of memory, then tries to write to memory that was 
not allocated. The call to _debug_tfree invokes _theap_check, which detects the 
error, generates several messages, and stops the program. 
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Note: You must compile this example with the /Tm /Gt options to map the free 
calls to _debug_tfree. 

#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

int main(void) 

{ 

char *ptr; 

/* malloc is mapped to _debug_tmal1oc */ 
if (NULL == (ptr = malloc(lOO))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

memset (ptr, 'x 1 , 105); /* Overwrites storage that was not allocated */ 

free(ptr); 
return 0; 

/**************************************************************************** 

The output should be similar to : 


End of allocated object 0x00080120 was overwritten at 0x00080184. 

The first eight bytes of the memory block (in hex) are: 7878787878787878. 
This memory block was (re)allocated at line number 10 in _debug_tmal 1 o.c. 
Heap state was valid at line 10 of _debug_tmallo.c. 

Memory error detected at line 15 of _debug_tmal1o.c. 
****************************************************************************/ 

} 



“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“Tiled Debug Functions” on page 32 
“_debug_mal 1 oc — Allocate Memory” on page 145 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 
“mal loc — Reserve Storage Block” on page 403 

“_tdump_al located — Get Information about Allocated Tiled Memory” on 
page 649 

“_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

“_theap_check — Validate User Memory Heap” on page 661 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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debug treal loc — Reallocate Tiled Memory Block 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *_debug_trealloc(void *ptr, size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

The _debug_treal 1 oc function is the debug version of _treal 1 oc. Like _treal 1 oc, 
it reallocates the block of tiled memory pointed to by ptr to a new size , specified in 
bytes. The block of memory must have been allocated using a tiled memory 
management function. _debug_treal loc also sets any new memory it allocates to 
OxAA, so you can easily locate instances where your program tries to use the data in 
memory without initializing it first. 

In addition, _debug_treal 1 oc makes an implicit call to _theap_check, and stores 
the file name fi le and the line number line where the storage is reallocated. This 
information can be used later by the _theap_check and _tdump_al 1 ocated or 
_tdump_al 1 ocated_del ta functions. 

If ptr is NULL, _debug_treal 1 oc behaves like _debug_tmal 1 oc (or mal 1 oc) and 
allocates the block of memory. 

To use _debug_trealloc, you must compile with the debug memory and tiled 
memory compiler options (/Tm /Gt). These options map all real loc calls to 
_debug_treal 1 oc (you can also call _debug_treal 1 oc explicitly). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

_debug_treal 1 oc works just like _debug_real 1 oc except that it reallocates tiled 
memory instead of regular memory. If you have objects that may be accessed by 
16-bit code, you should store them in tiled memory. Tiled memory is guaranteed not 
to cross 64K boundaries, as long as the object is less than 64K in size. Objects larger 
than 64K in size are aligned on 64K boundaries, but will also cross 64K boundaries. 
Tiled memory from the VisualAge C++ runtime heap is limited to 512 MB per 
process. You can also create your own heaps of tiled memory, which can be larger 
in size. See “Managing Memory” in the Programming Guide for more information. 

Return Value _debug_treal loc returns a pointer to the reallocated memory block. The ptr 
argument to _debug_treal 1 oc is not necessarily the same as the return value, 
because the _debug_treal 1 oc might change the memory location. 
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If size is 0, _debug_treal loc returns NULL. If not enough memory is available to 
expand the block to the given size, the original block is unchanged and NULL is 
returned. 



This example uses _debug_tmal loc to allocate 5 bytes of storage, then attempts to 
write to storage that was not allocated. The call to _debug_treal loc invokes 
_theap_check, which detects the error, generates several messages, and stops the 
program. 

Note: You must compile this example with the /Tm /Gt options to map the real 1 oc 
calls to _debug_treal 1 oc. 

#include <stdlib.h> 

#include <stdio.h> 


int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = mal1oc(5))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

memset (ptr, 'x 1 , 7); /* Overwrites storage that was not allocated */ 

/* realloc is mapped to _debug_treal1oc */ 
if (NULL == (ptr = realloc(ptr, 10))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

free(ptr); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

End of allocated object 0x00080120 was overwritten at 0x00080125. 

The first eight bytes of the memory block (in hex) are: 78787878787878DD. 
This memory block was (re)al1ocated at line number 8 in _debug_treallo.c. 
Heap state was valid at line 8 of _debug_treallo.c. 

Memory error detected at line 15 of _debug_treal1o.c. 
****************************************************************************/ 

} 



“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“Tiled Debug Functions” on page 32 

“_debug_real 1 oc — Reallocate Memory Block” on page 147 
“_debug_tcal loc — Reserve and Initialize Tiled Memory” on page 149 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_theapmin — Release Unused Tiled Memory” on page 153 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
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“_tdump_al located — Get Information about Allocated Tiled Memory” on 
page 649 

“_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

“_theap_check — Validate User Memory Heap” on page 661 
“_trealloc — Reallocate Tiled Storage Block” on page 679 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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_debug_ucal 

Format 

Description 


Return Value 



oc — Reserve and Initialize Memory from User Heap 

linclude <umalloc.h> 

void *_debug_ucalloc(Heap_t heap, size_t num, size_t size, 
const char *file, size_t line); 

Language Level: Extension 

_debug_ucal 1 oc is the debug version of _ucal 1 oc. Like _ucal 1 oc, it allocates 
memory from the heap you specify for an array of num elements, each of length size 
bytes. It then initializes all bits of each element to 0. 

In addition, _debug_ucal loc makes an implicit call to _uheap_check, and stores the 
name of the file fi le and the line number l ine where the storage is allocated. This 
information can be used later by the _uheap_check and _udump_al 1 ocated or 
_udump_al 1 ocated_del ta functions. 

To use _debug_ucal loc, you must compile with the debug memory (/Tm) compiler 
option, the /Tm compiler option. This option maps all _ucal 1 oc calls to 
_debug_ucal 1 oc (you can also call _debug_ucal 1 oc explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

_debug_ucal 1 oc works just like _debug_cal 1 oc except that you specify the heap to 
use; _debug_calloc always allocates from the default heap. 

If the heap does not have enough memory for the request, _debug_ucal loc calls the 
getmore^fn that you specified when you created the heap with _ucreate. 

To reallocate or free memory allocated with _debug_ucal 1 oc, use the 
non-heap-specific _debug_real 1 oc and _debug_free. These functions always check 
what heap the memory was allocated from. 

_debug_ucal 1 oc returns a pointer to the reserved space. If size or num was 
specified as zero, or if your getmore^fn cannot provide enough memory, 
_debug_ucal 1 oc returns NULL. Passing _debug_ucal 1 oc a heap that is not valid 
results in undefined behavior. 

This example creates a user heap and allocates memory from it with 
_debug_ucal 1 oc. It then attempts to write to memory that was not allocated. When 
_debug_free is called, _uheap_check detects the error, generates several messages, 
and stops the program. 
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Note: You must compile this example with the /Tm option to map the _ucal 1 oc 
calls to _debug_ucalloc and free to _debug_free. 

#include <stdlib.h> 

#include <stdio.h> 

#inc1ude <umal1 oc.h> 

#include <string.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptr = _ucalloc(myheap, 100, 1))) { 
puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x', 105); /* Overwrites storage that was not allocated */ 

free(ptr); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

End of allocated object 0x00073890 was overwritten at 0x000738f4. 

The first eight bytes of the memory block (in hex) are: 7878787878787878. 

This memory block was (re)allocated at line number 14 in _debug_ucal1o.c. 

Heap state was valid at line 14 of _debug_ucal1o.c. 

Memory error detected at line 19 of _debug_ucal1o.c. 
****************************************************************************/ 

} 


• “Managing Memory” in the Programming Guide 

• “Debugging Your Heaps” in the Programming Guide 

• “Differentiating between Memory Management Functions” on page 28 

• “cal loc — Reserve and Initialize Storage” on page 80 

• “_debug_cal loc — Allocate and Initialize Memory” on page 139 

• “_debug_free — Release Memory” on page 141 

• “_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 

• “_ucal 1 oc — Reserve and Initialize Memory from User Heap” on page 686 

• “_ucreate — Create a Memory Heap” on page 690 

• “_udump_al 1 ocated — Get Information about Allocated Memory in Heap” on 
page 699 

• “_uheap_check — Validate User Memory Heap” on page 705 

• “<umalloc.h>” on page 820 
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debug uheapmi n — Release Unused Memory in User Heap 

Format linclude <umalloc.h> 

int _debug_uheapmin(Heap_t heap, const char *file, size_t line); 

Description Language Level: Extension 

_debug_uheapmi n is the debug version of _uheapmi n. Like _uheapmi n, it returns all 
unused memory blocks from the specified heap to the operating system. 

To return the memory, _debug_uheapmi n calls the release^fn you supplied when 
you created the heap with _ucreate. If you do not supply a release_fn, 
_debug_uheapmi n has no effect and returns 0. 

In addition, _debug_uheapmi n makes an implicit call to _uheap_check to validate the 
heap. 

_debug_uheapmi n works just like _debug_heapmi n except that you specify the heap 
to use; _debug_heapmi n always uses the default heap. 

To use _debug_uheapmin, you must compile with the debug memory (/Tm) compiler 
option. This option maps all _uheapmin calls to _debug_uheapmi n (you can also call 
_debug_uheapmi n explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Return Value If successful, _debug_uheapmi n returns 0. A nonzero return value indicates failure. 

If the heap specified is not valid, _debug_uheapmi n generates an error message with 
the file name and line number where the call to _debug_uheapmi n was made. 

This example creates a heap and allocates memory from it, then uses 
_debug_heapmi n to release the memory. 

Note: You must compile this example with the /Tm option to map the _uheapmin 
calls to _debug_uheapmin. 
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#include <stdlib. h> 

#include <stdio.h> 

#include <umal1 oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

/* Allocate a large object */ 

if (NULL == (ptr = _umalloc(myheap, 60000))) { 

puts("Cannot allocate memory from user heap.\n"); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x', 60000); 
free(ptr); 

/* _debug_uheapmin will attempt to return the freed object to the system */ 
if (0 != _uheapmin(myheap)) { 

puts("_debug_uheapmin returns failed.\n"); 
exit(EXIT_FAILURE); 

} 

return 0; 


• “Managing Memory” in the Programming Guide 

• “Debugging Your Heaps” in the Programming Guide 

• “Differentiating between Memory Management Functions” on page 28 

• “_heapmin — Release Unused Memory from Default Heap” on page 327 

• “_ucreate — Create a Memory Heap” on page 690 

• “_udump_al 1 ocated — Get Information about Allocated Memory in Heap” on 
page 699 

• “_uheap_check — Validate User Memory Heap” on page 705 

• “_uheapmin — Release Unused Memory in User Heap” on page 709 

• “<umalloc.h>” on page 820 
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debug umal 1 oc — Reserve Memory Blocks from User Heap 

Format linclude <umalloc.h> 

void *_debug_umal1oc(Heap_t heap, size_t size, 

const char *file, size_t line); 

Description Language Level: Extension 

_debug_umal 1 oc is the debug version of _umal 1 oc. Like _umal 1 oc, it reserves 
storage space from the heap you specify for a block of size bytes. _debug_umal loc 
also sets all the memory it allocates to GxAA, so you can easily locate instances where 
your program uses the data in the memory without initializing it first. 

In addition, _debug_umal loc makes an implicit call to _uheap_check, and stores the 
name of the file fi le and the line number l ine where the storage is allocated. This 
information can be used later by the _uheap_check and _udump_al 1 ocated or 
_udump_al 1 ocated_del ta functions. _debug_umal 1 oc also sets all the memory it 
allocates to GxAA; this can help you debug problems where your program uses the data 
in the memory without initializing it. 

_debug_umal 1 oc works just like _debug_mal 1 oc except that you specify the heap to 
use; _debug_mal 1 oc always allocates from the default heap. 

If the heap does not have enough memory for the request, _debug_umal loc calls the 
getmore^fn that you specified when you created the heap with _ucreate. 

To use _debug_umal loc, you must compile with the debug memory (/Tm) compiler 
option. This option maps all _umal loc calls to _debug_umal loc (you can also call 
_debug_umal 1 oc explicitly). 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

To reallocate or free memory allocated with _debug_umal 1 oc, use the 
non-heap-specific _debug_real 1 oc and _debug_free. These functions always check 
what heap the memory was allocated from. 

Return Value _debug_umalloc returns a pointer to the reserved space. If size was specified as 
zero, or the getmore^fn cannot provide enough memory, _debug_umal loc returns 
NULL. Passing _debug_umal loc a heap that is not valid results in undefined 
behavior. 

--» This example creates a heap myheap and uses _debug_umal loc to allocate 100 bytes 

wjK front it. It then attempts to overwrite storage that was not allocated. The call to 
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_debug_free invokes _uheap_check, which detects the error, generates messages, 
and ends the program. 

Note: You must compile this example with the /Tm option to map _umal 1 oc to 
_debug_umal loc and free to _debug_free. 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 

#include <string.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptr = _umalloc(myheap, 100))) { 

puts("Cannot allocate memory from user heap.\n"); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x', 105); /* Overwrites storage that was not allocated */ 

free(ptr); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

End of allocated object 0x00073890 was overwritten at OxOO0738f4. 

The first eight bytes of the memory block (in hex) are: 7878787878787878. 

This memory block was (re)allocated at line number 14 in _debug_umal1o.c. 

Heap state was valid at line 14 of _debug_umal1o.c. 

Memory error detected at line 19 of _debug_umal 1 o.c. 
****************************************************************************/ 

} 

• “Managing Memory” in the Programming Guide 

• “Debugging Your Heaps” in the Programming Guide 

• “Differentiating between Memory Management Functions” on page 28 

• “_debug_free — Release Memory” on page 141 

• “_debug_mal 1 oc — Allocate Memory” on page 145 

• “_debug_ucal 1 oc — Reserve and Initialize Memory from User Heap” on 
page 160 

• “mal loc — Reserve Storage Block” on page 403 

• “_ucreate — Create a Memory Heap” on page 690 

• “_udump_al 1 ocated — Get Information about Allocated Memory in Heap” on 
page 699 

• “_umal 1 oc — Reserve Memory Blocks from User Heap” on page 717 

• “_uheap_check — Validate User Memory Heap” on page 705 

• “<umalloc.h>” on page 820 
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difftime — 

Format 

Description 

Return Value 



Compute Time Difference 

linclude <time.h> 

double difftime(time_t time2, time_t timel ); 

Language Level: ANSI, SAA, POSIX, XPG4 

difftime computes the difference in seconds between time2 and timel. 

The difftime function returns the elapsed time in seconds from timel to time2 as 
a double precision number. Type time_t is defined in <time.h>. 

This example shows a timing application using difftime. The example calculates 
how long, on average, it takes to find the prime numbers from 2 to 10000. 

#include <time.h> 

#include <stdio.h> 

Idefine RUNS 1000 

Idefine SIZE 10000 

int mark[SIZE]; 

int main(void) 

{ 

time_t start,finish; 
int i,loop,n,num; 

time(&start); 

/* This loop finds the prime numbers between 2 and SIZE */ 

for (loop = 0; loop < RUNS; ++1oop) { 
for (n - 0; n < SIZE; ++n) 
mark[n] = 0; 
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/* This loops marks all the composite numbers with -1 */ 

for (num = 0, n = 2; n < SIZE; ++n) 
if (!mark[n]) { 

for (i = 2*n; i < SIZE; i += n) 
mark[i] = -1; 

++num; 


time(&finish); 

printf("Program takes an average of %f seconds to find %d primes.\n", 
difftime(finish, start)/RUNS, num); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

Program takes an average of 0.106000 seconds to find 1229 primes. 
****************************************************************************/ 


• “asctime — Convert Time to Character String” on page 55 

• “ctime — Convert Time to Character String” on page 129 

• “gmtime— Convert Time” on page 321 

• “localtime — Convert Time” on page 385 

• “mktime — Convert Local Time” on page 438 

• “strftime — Convert to Formatted Time” on page 586 

• “t i me — Determine Current Time” on page 666 

• “<time.h>” on page 819 
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disable — Disable Interrupts 

Format linclude <builtin.h> 

void _disable( void ); 

Description Language Level: Extension 

_di sabl e disables interrupts by executing the CLI machine instruction. It disables 
interrupts until the instruction after a call to _enable has been executed. 

Note: _di sabl e is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _di sabl e. 

• You cannot parenthesize a call to _disable. (Parentheses specify a call to the 
function's backing code, and _disable has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 

Return Value This function has no return value. 

In this example, _di sabl e disables interrupts by executing a CLI instruction. 

#include <bui1tin.h> 

int main(void) 

{ 

/* - -k / 

/* The expected assembler instruction looks like this : */ 

/* CLI */ 

l k - k / 

_di sable(); 
return 0; 

} 

• “_enable — Enable Interrupts” on page 194 

• “_interrupt — Call Interrupt Procedure” on page 346 

• “<builtin.h>” on page 801 
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div — Calculate Quotient and Remainder 

Format linclude <stdlib.h> 

div_t div(int numerator, int denominator); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

div calculates the quotient and remainder of the division of numerator by 
denominator. 

Return Value div returns a structure of type div_t, containing both the quotient int quot and the 
remainder int rem. If the return value cannot be represented, its value is undefined. 
If denominator is 0, an exception will be raised. 

This example uses div to calculate the quotients and remainders for a set of two 
dividends and two divisors. 

#inc1ude <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

int num[2] 
int den[2] 
div_t ans; 

short i,j; 

printf("Results of division:\n"); 
for (i = 0; i < 2; i++) 
for (j =0; j < 2; j++) { 
ans = div(num[i], den [j]); 

printf ("Dividend: %61d Divisor: %61d", num[i], den [j]); 
printf(" Quotient: %61d Remainder: %61d\n", ans.quot, ans.rem); 

} 

return 0; 

/**************************************************************************** 

The output should be: 

Results of division: 

Dividend: 45 Divisor: 7 Quotient: 6 Remainder: 3 

Dividend: 45 Divisor: -7 Quotient: -6 Remainder: 3 

Dividend: -45 Divisor: 7 Quotient: -6 Remainder: -3 

Dividend: -45 Divisor: -7 Quotient: 6 Remainder: -3 

****************************************************************************/ 

} 

• “1 div — Perform Long Division” on page 373 

• “<stdlib.h>” on page 816 



= { 45,-45 }; 

= { 7,-7 }; 

/* div_t is a struct type containing two ints: 

'quot' stores quotient; 'rem' stores remainder */ 



Chapter 3. Library Functions 169 



DLL_InitTerm 


DLL InitTerm — Initialize and Terminate DLL Environment 

Format unsigned long _System _DLL_InitTerm(unsigned long modhandle, 

unsigned 1ong flag ); 

/* no header file - defined in runtime startup code */ 

Description Language Level: Extension 

_DLL_Ini tTerm is the initialization and termination entry point for a DLL. When 
each new process gains access to the DLL, _DLL_Ini tTerm initializes the necessary 
environment for the DLL, including storage, semaphores, and variables. When each 
process frees its access to the DLL, _DLL_InitTerm terminates the DLL environment 
created for that process. 

The default _DLL_Ini tTerm function supplied by VisualAge C++ performs the 
actions required to initialize and terminate the runtime environment, or for subsystem 
DLLs, to initialize and terminate memory functions. It is called automatically when 
you link to the DLL. If your DLL requires initialization or termination actions in 
addition to the actions performed in the default function, you will need to create your 
own _DLL_Ini tTerm function. 

If the value of the flag parameter is 0, the DLL environment is initialized. If the 
value of the flag parameter is 1, the DLL environment is ended. 

The modhandle parameter is the module handle assigned by the operating system for 
this DLL. You can use the module handle as a parameter to various OS/2 API calls. 
For example, you can call DosQueryModul eName with the module handle to return the 
fully-qualified path name of the DLL, which tells you where the DLL was loaded 
from. 

Because it is called by the operating system loader, you must compile your 
_DLL_Ini tTerm function with _System linkage. 

For more information on creating your own _DLL_Ini tTerm function, see the chapter 
Building Dynamic Link Libraries in the Programming Guide. 

Note: A _DLL_Ini tTerm function for a subsystem DLL has the same prototype, but 
the content of the function is different because there is no runtime environment to 
initialize or terminate. For more information on building subsystem DLLs, see the 
section Building a Subsystem DLL in the Programming Guide. 

Return Value The return code from _DLL_Ini tTerm tells the loader if the initialization or 

termination was performed successfully. If the call was successful, _DLL_Ini tTerm 
returns a nonzero value. A return code of 0 indicates that the function failed. If a 
failure is indicated, the loader will not load the program that is accessing the DLL. 
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This example shows the _DLL_Ini tTerm function from the VisualAge C++ sample 
program for building DLLs. 

Idefine INCL_D0SM0DU LEMGR 
Idefine INCL_DOSPROCESS 
#include <os2.h> 

#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

/* _CRT_init is the C run-time environment initialization function. */ 

/* It will return 0 to indicate success and -1 to indicate failure. */ 

int _CRT_init(void); 

#ifdef STATIC_LINK 

/* _CRT_term is the C run-time environment termination function. */ 

/* It only needs to be called when the C run-time functions are statically */ 

/* linked. */ 

void _CRT_term(void); 

#e 1 se 

/* A clean up routine registered with DosExitList must be used if runtime */ 

/* calls are required and the runtime is dynamically linked. This will */ 

/* guarantee that this clean up routine is run before the library DLL is */ 

/* terminated. */ 

static void _System cleanup(ULONG ulReason); 

#endi f 

size_t nSize; 
int *pArray; 

/* _DLL_InitTerm is the function that gets called by the operating system */ 

/* loader when it loads and frees this DLL for each process that accesses */ 

/* this DLL. However, it only gets called the first time the DLL is loaded */ 

/* and the last time it is freed for a particular process. The system */ 

/* linkage convention MUST be used because the operating system loader is */ 

/* calling this function. */ 

unsigned long _System _DLL_InitTerm(unsigned long hModule, unsigned long 

ul FI ag) 

{ 

size_t i; 

APIRET rc; 

char namebuf[CCHMAXPATH]; 
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/* If ulFlag is zero then the DLL is being loaded so initialization should*/ 
/* be performed. If ulFlag is 1 then the DLL is being freed so */ 

/* termination should be performed. */ 

switch (ulFlag) { 
case 0 : 

/•kic-kle-k-k-k-k-k'k-k-k-k-k-k'k-kick-k-klck-k'k-k-k'k-k-k'k-k-k-k-k-k-k-kick-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-kick-k-k-k-kick-k-klc/ 

/* The C run-time environment initialization function must be */ 

/* called before any calls to C run-time functions that are not */ 

/* inlined. */ 

/•kit-kle-kic-k-klt'k-k-kle-k-kle-k-k'k-k-k'k'k-k'k-k-klck-klckick-k-k'k-k-klck-klck-k-k-k-k'k-k-k'k-kick-k-k'k-k-k'k-k-k'k-k-kle/ 

if (_CRT_init() == -1) 
return OUL; 

#ifndef STATIC LINK 


/•k-k-k'k-k-k-k-k-k-k-k-k'k'k-k-k-k-k'k-k-k-k-k-k'k-kit'k-k-k-k-k-k-k-k-k'k-kick-k-k-k-k-klck-k'k-kick-k-k'k-kick-k-k'k-k-k-k-k-k-k/ 

/* A DosExitList routine must be used to clean up if runtime calls */ 
/* are required and the runtime is dynamically linked. */ 

/•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k1ck-k‘k-k-k‘k-k-k‘k-k-k‘k/ 


if (rc = DosExitList(0X0O0OFF0O|EXLST_ADD, cleanup)) 
printf("DosExitList returned %lu\n", rc); 

#endif 

if (rc = DosQueryModuleName(hModule, CCHMAXPATH, namebuf)) 
printf("DosQueryModuleName returned %lu\n", rc); 
el se 

printf("The name of this DLL is %s\n", namebuf); 
srand(17); 

nSize = (rand()%128)+32; 

printf("The array size for this process is %u\n", nSize); 
if ((pArray = malloc(nSize *sizeof(int))) == NULL) { 

printf("Could not allocate space for unsorted array.\n"); 
return OUL; 


for (i = 0; i < nSize; ++i) 
pArray [i] = rand(); 
break; 
case 1 : 

#ifdef STATIC_LINK 

printf("The array will now be freed.\n"); 
free(pArray); 

_CRT_term(); 

#endif 

break; 
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default : 

printf("ulFIag = %lu\n", ulFlag); 
return OUL; 


/* A non-zero value must be returned to indicate success. */ 

return 1UL; 

} 

#ifndef STATIC_LINK 

static void cl eanup(ULONG ulReason) 

{ 

if (!ulReason) { 

printf("The array will now be freed.\n"); 
free(pArray); 

} 

DosExitList(EXLST_EXIT, cleanup); 
return ; 

} 

#endi f 


The following example shows the _DLL_Ini tTerm function from the VisualAge C++ 
sample for building subsystem DLLs. 


/* This example provides 5 external entrypoints of which 2 are exported for */ 
/* use by client processes. The entrypoints are: */ 
/* */ 
/* _DLL_InitTerm - Initialization/Termination function for the DLL that is */ 
/* invoked by the loader. When the /Ge- compile option is */ 
/* used the linker is told that this is the function to */ 
/* execute when the DLL is first loaded and last freed for */ 
/* each process. */ 
/* */ 
/* DLLREGISTER - Called by _DLL_InitTerm for each process that loads the */ 
/* DLL. */ 
/* */ 
/* DLLINCREMENT - Accepts a count from its client and adds this value to */ 
/* the process and system totals. */ 
/* */ 
/* DLLSTATS - Dumps process and system totals on behalf of its client. */ 
/* */ 
/* DLLDEREGISTER- Called by _DLL_InitTerm for each process that frees the */ 
/* DLL. */ 
/* */ 


/******************************************************************************/ 
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#define INCL_DOS 
#define INCL_DOSERRORS 
#define INCL_NOPMAPI 
#include <os2.h> 

#include <stdio.h> 

#include "sample05.h" 

unsigned long _System _DLL_InitTerm( unsigned long hModule, unsigned long ulFIag ) 

static unsigned long DLLREGISTER( void ); 
static unsigned long DLLDEREGISTER( void ); 

#define SHARED_SEMAPHORE_NAME "\\SEM32\\SAMPLE05\\DLL.LCK" 

/* The following data will be per-process data. It will not be shared among */ 

/* different processes. */ 

static HMTX hmtxSharedSem; /* Shared semaphore */ 

static ULONG ulProcessTotal; /* Total of increments for a process */ 

static PID pidProcess; /* Process identifier */ 

/* This is the global data segment that is shared by every process. */ 

#pragma data_seg( GLOBAL_SEG ) 

static ULONG ulProcessCount; /* total number of processes */ 

static ULONG ulGrandTotal; /* Grand total of increments */ 

/* _DLL_InitTerm() - called by the loader for DLL initialization/termination */ 

/* This function must return a non-zero value if successful and a zero value */ 

/* i f unsuccessful. */ 

unsigned long _DLL_InitTerm( unsigned long hModule, unsigned long u1 FIag ) 

{ 

APIRET rc; 

/* If u1 FIag is zero then initialization is required: */ 

/* If the shared memory pointer is NULL then the DLL is being loaded */ 

/* for the first time so acquire the named shared storage for the */ 

/* process control structures. A linked list of process control */ 

/* structures will be maintained. Each time a new process loads this */ 

/* DLL, a new process control structure is created and it is inserted */ 

/* at the end of the list by calling DLLREGISTER. */ 

/* */ 

/* If u 1 FI ag is 1 then termination is required: */ 

/* Call DLLDEREGISTER which will remove the process control structure */ 

/* and free the shared memory block from its virtual address space. */ 
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switch( ulFlag ) 

{ 

case 0: 

if ( !ulProcessCount ) 

{ 

_rmem_init(); 

/* Create the shared mutex semaphore. */ 

if ( ( rc = DosCreateMutexSem( SHARED_SEMAPHORE_NAME, 

&hmtxSharedSem, 

0 . 

FALSE ) ) != N0_ERR0R ) 

{ 

printf( "DosCreateMutexSem rc = %lu\n", rc ); 
return 0; 

} 


/* Register the current process. */ 

if ( DLLREGISTER( ) ) 
return 0; 

break; 

case 1: 

/* De-register the current process. */ 

if ( DLLDEREGISTER( ) ) 
return 0; 

_rmem_term(); 

break; 

default: 
return 0; 

} 

/* Indicate success. Non-zero means success!!! */ 

return 1; 

} 


/* DLLREGISTER - Registers the current process so that it can use this 
/* subsystem. Called by _DLL_InitTerm when the DLL is first 

/* loaded for the current process. 


*/ 

*/ 

*/ 
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static unsigned long DLLREGISTER( void ) 

{ 

APIRET rc; 

PTIB ptib; 

PPIB ppib; 

/* Get the address of the process and thread information blocks. */ 

if ( ( rc = DosGetInfoBlocks( &ptib, &ppib ) ) != N0_ERR0R ) 

{ 

printf( "DosGetlnfoBlocks rc = %lu\n", rc ); 
return rc; 

} 

/* Open the shared mutex semaphore for this process. */ 

if ( ( rc = DosOpenMutexSem( SHARED_SEMAPHORE_NAME, 

&hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosOpenMutexSem rc = %lu\n", rc ); 
return rc; 

} 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %lu\n", rc ); 

DosCloseMutexSem( hmtxSharedSem ); 
return rc; 

} 

/* Increment the count of processes registered. */ 

++ulProcessCount; 

/* Initialize the per-process data. */ 

ulProcessTotal = 0; 
pidProcess = ppib->pib_ulpid; 

/* Tell the user that the current process has been registered. */ 

printf( "\nProcess %1u has been registered.\n\n", pidProcess ); 
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/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 


return 0; 

} 


/* DLLINCREMENT - Increments the process and global totals on behalf of the */ 
/* calling program. */ 

int DLLINCREMENT( int incount ) 

{ 

APIRET rc; /* return code from DOS APIs */ 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %lu\n", rc ); 
return rc; 

} 


/* Increment the counts the process and grand totals. */ 

ulProcessTotal += incount; 
ulGrandTotal += incount; 

/* Tell the user that the increment was successful. */ 

printf( "\nThe increment for process %lu was successful.\n\n", pidProcess ); 

/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 


return 0; 

} 
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/* DLLSTATS - Prints process and grand totals. */ 

int DLLSTATS( void ) 

{ 

APIRET rc; 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %lu\n", rc ); 
return rc; 

} 


/* Print out per-process and global information. 

printf( "\nCurrent process identifier = %lu\n", pidProcess ); 

printf( "Current process total = %lu\n", ulProcessTotal ); 

printf( "Number of processes registered = %lu\n", ulProcessCount ); 

printf( "Grand Total = %lu\n\n", ulGrandTotal ); 

/* Release the shared mutex semaphore. 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 


*/ 


*/ 


return 0; 

} 


178 VisualAge C++ C Library Reference 



DLL_InitTerm 


/* DLLDEREGISTER - Deregisters the current process from this subsystem. */ 

/* Called by _DLL_InitTerm when the DLL is freed for the */ 

/* last time by the current process. */ 

static unsigned long DLLDEREGISTER( void ) 

{ 

APIRET rc; 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %lu\n", rc ); 
return rc; 

} 


/* Decrement the count of processes registered. */ 

--ulProcessCount; 

/* Tell the user that the current process has been deregistered. */ 

printf( "\nProcess %lu has been deregistered.\n\n", pidProcess ); 

/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 

/* Close the shared mutex semaphore for this process. */ 

if ( ( rc = DosCloseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosCloseMutexSem rc = %lu\n", rc ); 
return rc; 

} 


return 0; 

} 


• Building a Dynamic Link Library in the Programming Guide 

• Building a Subsystem DLL in the Programming Guide 

• “_CRT_init — Initialize DLL Runtime Environment” on page 118 

• “_CRT_term — Terminate DLL Runtime Environment” on page 122 

• “_rmem_init — Initialize Memory Functions for Subsystem DLL” on page 501 

• “_rmem_term — Terminate Memory Functions for Subsystem DLL” on page 507 

• “_tmem_init — Initialize Memory Functions for Subsystem DLL” on page 669 

• “_tmem_term — Terminate Memory Functions for Subsystem DLL” on page 670 
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dump allocated — Get Information about Allocated Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void _dump_al1ocated(int nbytes ); 

Description Language Level: Extension 

_dump_al located prints information to stderr about each memory block that is 
currently allocated and was allocated using the debug memory management functions 
(_debug_cal 1 oc, _debug_mal 1 oc, and so on). 

Use nbytes to specify how many bytes of each memory block are to be printed. If 
nbytes is a: 

Negative value Prints all bytes of each block. 

0 Prints no bytes. 

Positive value Prints the specified number of bytes or the entire block, whichever is 
smaller. 

Call _dump_al 1 ocated at points in your code where you want a report of the 
currently allocated memory. For example, a good place to call _dump_al 1 ocated is a 
point where most of the memory is already freed and you want to find a memory 
leak, such as at the end of a program. 

_dump_al located prints the information to stderr, but you can change the 
destination with the _set_crt_msg_handl e function. You can also use 
_dump_al 1 ocated_del ta to display information only about the memory that was 
allocated since the previous call to _dump_al 1 ocated or _dump_al 1 ocated_del ta. 

To use _dump_al 1 ocated and the debug memory management functions, you must 
compile with the debug memory (/Tm) compiler option. 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Heap-specific and tiled versions of this function (_udump_al located and 
_tdump_allocated) are also available. _dump_al 1 ocated always prints information 
about memory allocated from the default heap. 

Return Value There is no return value. 
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This example allocates three memory blocks, and then calls _dump_al 1 ocated to 
dump information and the first 8 bytes for each memory block. 

Note: You must compile this example with the /Tm option to map the memory 
management functions to their debug versions. 

#include <stdlib.h> 

#include <string.h> 

#inc1ude <stdio.h> 

Idefine INIT_STR "lt\0works" 

Idefine INIT_STR_LEN (sizeof(INIT_STR) - 1) 

int main(void) { 
char *pBlockl; 
char *pBlock2; 
char *pBlock3; 

if (NULL == (pBlockl = mal1oc(35))) { /* allocate first memory block */ 

printf("Could not allocate first memory block.\n"); 
return EXIT_FAILURE; 

} 

memcpy(pBlockl, INIT_STR, INIT_STR_LEN); /* initialize first memory block */ 
if (NULL == (pBlock2 = calloc(2, 120))) { /* allocate second memory block */ 
printf("Could not allocate second memory block.\n"); 
return EXIT_FAILURE; 

} 

memcpy(pBlock2, INIT_STR, INIT_STR_LEN); /* initialize second memory block */ 
if (NULL == (pBlock3 = realloc(NULL, 2235))) {/* allocate third 

memory block */ 

printf("Could not allocate third memory block.\n"); 
return EXIT_FAILURE; 

} 


memcpy(pBlock3, INIT_STR, INIT_STR_LEN); /* initialize third memory block */ 
if (NULL == (pBlock3 = realloc(pBlock3, 300))) { /* reallocate third */ 

/* memory block to different size */ 

printf("Could not reallocate third memory block.\n"); 
return EXIT_FAILURE; 


_dump_al1ocated(8); /* show first eight bytes of each memory block */ 

return 0; 
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/**************************************************************************** 

The output should be similar to: 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0x00074310 Size: 0x0000012C (300) 

This memory block was (re)al1ocated at line number 32 in _dump_alloc.c. 
Memory contents: 49740077 6F726B73 [It.works ] 


Address: Ox00O738F0 Size: 0x000000-0 (240) 

This memory block was (re)al1ocated at line number 19 in _dump_alloc.c. 
Memory contents: 49740077 6F726B73 [It.works ] 


Address: 0x00073890 Size: 0x00000023 (35) 

This memory block was (re)al1ocated at line number 13 in _dump_alloc.c. 
Memory contents: 49740077 6F726B73 [It.works ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


} 


/ 



Memory Management in the Programming Guide 
Debugging Your Heaps in the Programming Guide 
“Differentiating between Memory Management Functions” on page 28 
“_debug_cal loc — Allocate and Initialize Memory” on page 139 
“_debug_free — Release Memory” on page 141 
“_debug_mal 1 oc — Allocate Memory” on page 145 
“_debug_real 1 oc — Reallocate Memory Block” on page 147 
“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_heap_check — Validate Default Memory Heap” on page 323 
“_udump_al located — Get Information about Allocated Memory in Heap” on 
page 699 

“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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dump allocated delta — Get Information about Allocated Memory 

Format linclude <std1ib.h> /* also in <malloc.h> */ 

void _dump_allocated_delta(int nbytes ); 

Description Language Level: Extension 

_dump_al 1 ocated_del ta prints information to stderr about each memory block 
allocated by a debug memory management function (_debug_mal 1 oc and so on) since 
the last call to _dump_al 1 ocated_del ta or _dump_al 1 ocated. 

_dump_al 1 ocated_del ta and _dump_al 1 ocated print the same type of information 
to stderr, but _dump_al located displays information about all blocks that have been 
allocated since the start of your program. 

Use nbytes to specify how many bytes of each memory block are to be printed. If 
nbytes is a: 

Negative value Prints all bytes of each block. 

0 Prints no bytes. 

Positive value Prints the specified number of bytes or the entire block, whichever 
is smaller. 

_dump_al 1 ocated_del ta prints the information to stderr, but you can change the 
destination with the _set_crt_msg_handl e function. 

A heap-specific version of this function, _udump_al 1 ocated_del ta, is also available. 
_dump_allocated_delta always displays information about the default heap. 

To use _dump_al 1 ocated_del ta and the debug versions of the memory management 
functions, specify the debug memory (/Tm) compiler option. 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) are mapped to their debug counterparts. To prevent 
a call from being mapped, parenthesize the function name. 


Return Value There is no return value. 



This example allocates some memory and calls _dump_al located to print 
information about the allocated blocks. It then allocates more memory, and calls 
_dump_allocated_delta again to print information about the allocations since the 
previous call. 

Note: You must compile this example with the /Tm option to map the memory 
management functions to their debug versions. 
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#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

int main(void) 

{ 

char *ptrl, *ptr2; 

if (NULL == (ptrl = malloc(10))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptrl, 'a', 5); 

_dump_al1ocated(10); 

if (NULL == (ptr2 = malloc(20))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptr2, 1 b', 5); 

_dump_al 1 ocated_delta(10); 

free(ptrl); 
free(ptr2); 
return 0; 

/**************************************************************************** 

The output should be similar to ; 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0x00073890 Size: OxOOOOOOOA (10) 

This memory block was (re)al1ocated at line number 9 in _dump_alloc_d.c. 
Memory contents: 61616161 61AAAAAA AAAA [aaaaaeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0X00O738D0 Size: 0x00000014 (20) 

This memory block was (re)al1ocated at line number 16 in _dump_alloc_d.c. 
Memory contents: 62626262 62AAAAAA AAAA [bbbbbeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


} 


/ 



“Differentiating between Memory Management Functions” on page 28 
“_debug_cal loc — Allocate and Initialize Memory” on page 139 
“_debug_mal 1 oc — Allocate Memory” on page 145 

“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_debug_real 1 oc — Reallocate Memory Block” on page 147 
“_set_crt_msg_handl e — Change Runtime Message Output Destination” on 
page 526 
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• “_tdump_al1ocated_delta 
on page 652 

• “_udump_al1ocated_delta 
Heap” on page 702 

• “<stdlib.h>” on page 816 

• “<malloc.h>” on page 810 


Get Information about Allocated Tiled Memory” 
Get Information about Allocated Memory in 
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dup — Associate Second Handle with Open File 

Format linclude <io.h> 

int dup(int handle ); 


Description Language Level: XPG4, Extension 

dup associates a second file handle with a currently open file. You can carry out 
operations on the file using either file handle because all handles associated with a 
given file use the same file pointer. Creation of a new handle does not affect the 
type of access allowed for the file. 

For example, given: 

handle2 = dup [handlel) 

handle2 will have the same file access mode (text or binary) as handlel. In 
addition, if handlel was originally opened with the 0_APPEND flag (described in 
“open — Open File” on page 447), handle2 will also have that attribute. 

Warning: Both handles share a single file pointer. If you reposition a file using 
handlel , the position in the file returned by handle2 will also change. 

If you duplicate a file handle for an open stream, the resulting file handle has the 
same restrictions as the original file handle. 

Note: In earlier releases of C Set ++, dup began with an underscore (_dup). 

Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _dup to dup for you. 


Return Value 


dup returns the next available file handle for the given file. It returns -1 if an error 
occurs and sets errno to one of the following values: 


Value 

EBADF 

EMFILE 

EOS2ERR 


Meaning 

The file handle is not valid. 

No more file handles are available. 

The call to the operating system was not successful. 
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This example makes a second file handle, fh3, refer to the same file as the file handle 
fh 1 using dup. The file handle fh2 is then associated with the file edopen.da2, and 
finally fh2 is forced to associate with edopen.dal dup2. 


#include <io.h> 

#include <stdio.h> 
#include <stdlib.h> 
#include <fcntl.h> 
linclude <sys\stat.h> 


int main(void) 

{ 

int fhl,fh2,fh3; 


if (-1 == (fhl = open("edopen.dal", 0_CREAT|0_TRUNC|0_RDWR, S_IREAD|S_IWRITE) 

)) 1 

perror("Unable to open edopen.dal"); 
return EXIT_FAILURE; 

} 

if (-1 == (fh3 = dup(fhl))) { /* fh3 refers to the sample file as fhl */ 

perror("Unable to dup"); 
close(fhl); 
return EXIT_FAILURE; 

} 

el se 

printf("Successfully performed dup handle.\n"); 
if (-1 == (fh2 = open("edopen.da2", 0_CREAT|0_TRUNC|0_RDWR, S_IREAD|S_IWRITE) 
)) { 

perror("Unable to open edopen.da2"); 

close(fhl); 

close(fh3); 

return EXIT_FAILURE; 

} 

if (-1 == dup2(fhl, fh2)) { /* Force fh2 to the refer to the same file */ 

/* as fhl. */ 

perror("Unable to dup2"); 

} 

el se 

printf("Successfully performed dup2 handle.\n"); 
close(fhl); 
close(fh2); 
close(fh3); 
return 0; 


Chapter 3. Library Functions 187 



dup 


/**************************************************************************** 

The output should be: 

Successfully performed dup handle. 

Successfully performed dup2 handle. 

****************************************************************************/ 

} 



“close — Close File Associated with Handle” on page 99 
“creat — Create New File” on page 115 

“dup2 — Associate Second Handle with Open File” on page 189 
“open — Open File” on page 447 
“_sopen — Open Shared File” on page 545 
“<io.h>” on page 804 


188 VisualAge C++ C Library Reference 




dup2 


dup2 — Associate Second Handle with Open File 

Format linclude <io.h> 

int dup2(int handlel, int handle2 ); 


Description Language Level: XPG4, Extension 

dup2 makes handle2 refer to the currently open file associated with handlel. You 
can carry out operations on the file using either file handle because all handles 
associated with a given file use the same file pointer. 

handle2 will point to the same file as handlel , but will retain the file access mode 
(text or binary) that it had before duplication. In addition, if handle2 was originally 
opened with the 0_APPEND flag, it will also retain that attribute. If handle2 is 
associated with an open file at the time of the call, that file is closed. 

Warning: Both handles share a single file position. If you reposition a file using 
handlel. the position in the file returned by handle2 will also change. 

If you duplicate a file handle for an open stream (using fileno), the resulting file 
handle has the same restrictions as the original file handle. 

Note: In earlier releases of C Set ++, dup2 began with an underscore (_dup2). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _dup2 to dup2 for you. 


Return Value dup2 returns 0 to indicate success. It returns -1 if an error occurs and sets errno to 
one of the following values: 


Value 

EBADF 

EMFILE 

EOS2ERR 


Meaning 

The file handle is not valid. 

No more file handles are available. 

The call to the operating system was not successful. 
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This example makes a second file handle, fh3, refer to the same file as the file handle 
fh 1 using dup. The file handle fh2 is then associated with the file edopen.da2, and 
finally fh2 is forced to associate with edopen.dal by the dup2 function. 


#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl.h> 
#include <sys\stat.h> 


int main(void) 

{ 

int fhl,fh2,fh3; 


if (-1 == (fhl = open("edopen.dal", 0_CREAT|0_TRUNC|0_RDWR, S_IREAD|S_IWRITE) 

)) { 

perror("Unable to open edopen.dal"); 
return EXIT_FAILURE; 

} 

if (-1 == (fh3 = dup(fhl))) { /* fh3 refers to the sample file as fhl */ 

perror("Unable to dup"); 
close(fhl); 
return EXIT_FAILURE; 

} 

else 

printf("Successfully performed dup handle.\n"); 
if (-1 == (fh2 = open("edopen.da2", 0_CREAT|0_TRUNC|0_RDWR, S_IREAD|S_IWRITE) 
)) { 

perror("Unable to open edopen.da2"); 

close(fhl); 

close(fh3); 

return EXIT_FAILURE; 

} 

if (-1 == dup2(fhl, fh2)) { /* Force fh2 to the refer to the same file */ 

/* as fhl. */ 

perror("Unable to dup2"); 


else 

printf("Successfully performed dup2 handle.\n"); 
close(fhl); 
close(fh2); 
close(fh3); 
return 0; 
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/**************************************************************************** 
The output should be: 

Successfully performed dup handle. 

Successfully performed dup2 handle. 

****************************************************************************/ 


• “close — Close File Associated with Handle” on page 99 

• “creat — Create New File” on page 115 

• “dup — Associate Second Handle with Open File” on page 186 

• “open — Open File” on page 447 

• “_sopen — Open Shared File” on page 545 

• “<io.h>” on page 804 
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ecvt — Convert Floating-Point to Character 


Format 

Description 


Return Value 


linclude <stdlib.h> 

char *_ecvt(double value, int ndigits, int *decptr, int *signptr ); 

Language Level: Extension 

_ecvt converts the floating-point number value to a character string. _ecvt stores 
ndigits digits of value as a string and adds a null character (\0). If the number of 
digits in value exceeds ndigits , the low-order digit is rounded. If there are fewer 
than ndigits digits, the string is padded with zeros. Only digits are stored in the 
string. 

You can obtain the position of the decimal point and the sign of value after the call 
from decptr and signptr. decptr points to an integer value that gives the position 
of the decimal point with respect to the beginning of the string. A 0 or a negative 
integer value indicates that the decimal point lies to the left of the first digit. 

signptr points to an integer that indicates the sign of the converted number. If the 
integer value is 0, the number is positive. If it is not 0, the number is negative. 

_ecvt also converts NaN and infinity values to the strings NAN and INFINITY, 
respectively. For more information on NaN and infinity values, see “Infinity and 
NaN Support” on page 33. 

Warning: For each thread, the _ecvt, _fcvt and _gcvt functions use a single, 
dynamically allocated buffer for the conversion. Any subsequent call that the same 
thread makes to these functions destroys the result of the previous call. 

_ecvt returns a pointer to the string of digits. Because of the limited precision of 
the double type, no more than 16 decimal digits are significant in any conversion. If 
it cannot allocate memory to perform the conversion. _ecvt returns NULL and sets 
errno to ENOMEM. 
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This example reads in two floating-point numbers, calculates their product, and prints 
out only the billions digit of its character representation. At most, 16 decimal digits 
of significance can be expected. The output assumes the user enters the numbers 
1000000 and 3000. 

#include <stdio.h> 

#include <stdlib.h> 

#include <math.h> 

int main(void) 

{ 

float x,y; 
double z; 

int w,b,decimal,sign; 
char *buffer; 

printf("Enter two floating-point numbers:\n"); 
if (2 != scanf("%e %e", &x, &y)) { 
printf ("input error.. An"); 
return EXIT_FAILURE; 

} 

z = x *y; 

printf("Their product is %g\n", z); 

w = Iogl0(fabs(z))+1.; 

buffer = _ecvt(z, w, &decimal, &sign); 

b = decimal-10; 

if (b < 0) 

printf("Their product does not exceed one bi11ion.\n"); 
el se 

if (b > 15) 

printf("The billions digit of their product is insignificantAn"); 
el se 

printf("The billions digit of their product is %c.\n", buffer[b]); 
return 0; 

/**************************************************************************** 

For the following input: 

1000000 3000 

The output should be: 

Enter two floating-point numbers: 

1000000 3000 
Their product is 3e+09 
The billions digit of their product is 3. 
****************************************************************************/ 


• “_fcvt — Convert Floating-Point to String” on page 217 

• “_gcvt — Convert Floating-Point to String” on page 294 

• “Infinity and NaN Support” on page 33 

• “<stdlib.h>” on page 816 
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enable — Enable Interrupts 

Format linclude <builtin.h> /* also defined in <stdlib.h> */ 

void _enable( void ); 

Description Language Level: Extension 

_enabl e enables interrupts by generating the STI machine instruction. Interrupts are 
enabled after the instruction following STI has been executed. If interrupts are 
disabled and you call _enable followed immediately by a call to _di sable, interrupts 
remain disabled. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _enabl e. 

• You cannot parenthesize an _enabl e function call because parentheses specify a 
call to the backing code for the function in the library. 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception will be generated. 

Return Value There is no return value. 

In this example, _enabl e enables interrupts by executing an STI instruction. 

#include <bui1tin.h> 

int main(void) 

{ 

/* - */ 

/* The expected assembler instruction looks like this : */ 

/* STI */ 

/* - -k / 

_enable(); 
return 0; 

} 

• “_di sable — Disable Interrupts” on page 168 

• “_interrupt — Call Interrupt Procedure” on page 346 

• “<builtin.h>” on page 801 
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_endthread 

Format 

Description 


Return Value 



- Terminate Current Thread 

linclude <stdlib.h> /* also in <process.h> */ 
void _endthread(void); 

Language Level: Extension 

_endthread ends a thread that you previously created with _begi nthread. When the 
thread has finished, it automatically ends itself with an implicit call to _endthread. 
You can also call _endthread explicitly to end the thread before it has completed its 
function, for example, if some error condition occurs. 

Notes: 

1. When using the _beginthread and _endthread functions, you must specify the 
/Gm+ compiler option to use the multithread libraries. 

2. If you use DosCreateThread, you must explicitly call _endthread to terminate the 
thread. 

There is no return value. 

In this example, the main program creates two threads, bonjour and au_revoir. The 
thread bonjour is forcibly terminated by a call to _endthread, while the au_revoir 
thread ends itself with an implicit call to _endthread. 

Note: You must compile this example with the /Gm+ option. 

#define INCL_D0S 
#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <process.h> 

void bonjour(void *arg) 

{ 

int i = 0; 
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while (i++ < 5) 

printf("Bonjour!\n"); 

_endthread(); /* This thread ends itself explicitly*/ 

puts("thread should terminate before printing this"); 


void au_revoir(void *arg) 

{ 

int i = 0; 

while (i++ < 5) 

printf("Au revoir!\n"); 

} 


/* This thread makes an implicit */ 
/* call to _endthread */ 


int main(void) 

{ 

unsigned long tidl; 
unsigned long tid2; 

tidl = _beginthread(bonjour, NULL, 8192, NULL); 
tid2 = _beginthread(au_revoir, NULL, 8192, NULL); 
if (-1 == tidl || -1 == tid2) { 

printf("Unable to start threads.\n"); 
return EXIT_FAILURE; 

} 

DosWaitThread(&tid2, DCWW_WAIT); /* wait until threads 1 and 2 */ 

DosWaitThread(&tidl, DCWW_WAIT); /* have been completed */ 

return 0; 

/**************************************************************************** 

The output should be similar to: 

Au revoir! 

Au revoir! 

Au revoir! 

Au revoir! 

Au revoir! 

Bonjour! 

Bonjour! 

Bonjour! 

Bonjour! 

Bonjour! 

****************************************************************************/ 



“_begi nthread — Create New Thread” on page 71 
/Gm+ option, in the User's Guide 
“<stdlib.h>” on page 816 
“<process.h>” on page 812 
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_eof — Determine End of File 

Format linclude <io.h> 

int _eof (int handle ); 

Description Language Level: Extension 

_eof determines whether the file pointer has reached the end-of-file for the file 

associated with handle. You cannot use_eof on a nonseekable file; it will fail. 


Return Value _eof returns the value 1 if the current position is the end of the file or 0 if it is 

not. A return value of -1 shows an error, and the system sets errno to the following 
values: 

Value Meaning 

EBADF File handle is not valid. 

EOS2ERR The call to the operating system was not successful. 



This example creates the file sample.dat and then checks if the file pointer is at the 
end of that file using the_ eof function. 

linclude <sys\stat.h> 

#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

int fh,returnValue; 

fh = creatCsample.dat", S_IREAD|S_IWRITE); 
if (-1 == fh) { 

perror("Error creating sample.dat"); 
return EXIT_FAILURE; 

} 

if (-1 == (returnValue = _eof(fh))) { 

perror("eof function error"); 
return EXIT_FAILURE; 

} 

if (1 == returnValue) 

printf("Fi1e pointer is at end-of-file position.\n"); 
el se 

printf("Fi1e pointer is not at end-of-file position.\n"); 
close(fh); 
return 0; 

/**************************************************************************** 
The output should be: 

File pointer is at end-of-file position. 
****************************************************************************/ 
i 


Chapter 3. Library Functions 197 



eof 



“_chsi ze — Alter Length of File” on page 92 

“creat — Create New File” on page 115 

“_fi 1 el ength — Determine File Length” on page 236 

“_sopen — Open Shared File” on page 545 

“open — Open File” on page 447 

“<io.h>” on page 804 
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erf - erfc — Calculate Error Functions 

Format linclude <math.h> 

double erf(double x ); 
double erfc(double x); 

Description Language Level: SAA, XPG4 

erf calculates the error function of 



erfc computes the value of 1.0 - erf(x). erfc is used in place of erf for large 
values of x. 


Return Value erf returns a double value that represents the error function, erfc returns a double 
value representing 1.0 - erf. 



This example uses erf and erfc to compute the error function of two numbers. 

#include <stdio.h> 

#include <math.h> 

double smal1x,largex.value; 


int main(void) 

{ 

smallx = 0.1; 
largex = 10.0; 

value = erf(smallx); /* value = 0.112463 */ 

printf("Error value for 0.1: %lf\n", value); 

value = erfc(largex); /* value = 2.088488e-45 */ 

printf("Error value for 10.0: %le\n", value); 
return 0; 

/**************************************************************************** 
The output should be: 

Error value for 0.1: 0.112463 
Error value for 10.0: 2.088488e-45 

****************************************************************************/ 

} 



“Bessel Functions — Solve Differential Equations” on page 74 
“gamma — Gamma Function” on page 293 
“<math.h>” on page 811 
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execl - execvpe — Load and Run Child Process 

Format linclude <process.h> 

int execl(char *pathname, char *argO, char *argl . 

char *argn, NULL) ; 

int execle(char * pathname , char *argO, char *argl . 

char *argn, NULL, char *envp[ ]); 

int execlp(char * pathname , char *argO, char *argl . 

char *argn , NULL); 

int _execlpe(char *pathname, char *argO, char *argl,..., 
char *argn, NULL, char *envp[ ]); 
int execv(char *pathname, char *argv[ ]); 
int execve(char * pathname , char *argv[ ],char *envp[ ]); 
int execvp(char *pathname, char *argv[ ]); 
int _execvpe(char *pathname, char *argv[ ], char *envp[ ]); 

Description Language Level: XPG4 (except _execlpe and _execvpe). Extension 

The exec functions load and run new child processes. The parent process is ended 
after the child process has started. Sufficient storage must be available for loading 
and running the child process. 

All of the exec functions are versions of the same routine; the letters at the end 
determine the specific variation: 

Letter Variation 

p Uses PATH environment variable to find the file to be run. 

1 Passes a list of command line arguments separately, 

v Passes to the child process an array of pointers to command-line 

arguments. 

e Passes to the child process an array of pointers to environment strings. 

Note: In earlier releases of C Set ++, all of the exec functions began with an 
underscore (_getpid). Because they are defined by the X/Open standard, the 
underscore has been removed. _execl pe and _execvpe retain the initial underscore 
because they are not included in the X/Open standard. For compatibility, 

VisualAge C++ will map the _exec functions to the correct exec function. 

The pathname argument specifies the file to run as the child process. The pathname 
can specify a full path from the root, a partial path from the current working 
directory, or a file name. If pathname does not have a file name extension or does 
not end with a period, the exec functions will add the .EXE extension and search for 
the file. If pathname has an extension, the exec function uses only that extension. If 
pathname ends with a period, the exec functions search for pathname with no 
extension. The execl p, _execlpe, execvp, and _execvpe functions search for the 
pathname in the directories that the PATH environment variable specifies. 


200 


VisualAge C++ C Library Reference 



execl — _execvpe 


You pass arguments to the new process by giving one or more pointers to character 
strings as arguments in the exec call. These character strings form the argument list 
for the child process. 

The compiler can pass the argument pointers as separate arguments (execl, execl e, 
execl p, and _execlpe) or as an array of pointers (execv, execve, execvp, and 
_execvpe). You should pass at least one argument, either argO or argv[0], to the 
child process. If you do not, an argument will be returned that points to the same file 
as the path name argument you specified. This argument may not be exactly identical 
to the path name argument you specified. A different value does not produce an 
error. 

Use the execl, execle, execlp, and _execlpe functions for the cases where you 
know the number of arguments in advance. The argO argument is usually a pointer 
to pathname. The argl through argn arguments are pointers to the character strings 
forming the new argument list. There must be a NULL pointer following argn to mark 
the end of the argument list. 

Use the execv, execve, execvp, and _execvpe functions when the number of 
arguments to the new process is variable. Pass pointers to the arguments of these 
functions as an array, argv[ ]. The argv[0] argument is usually a pointer to 
pathname. The argv[l] through argv[n] arguments are pointers to the character 
strings forming the new argument list. If argv[n] is the last parameter, then 
argv[n+I] must be NULL. 

Files that are open when you make an exec call remain open in the new process. In 
the execl, execlp, execv, and execvp calls, the child process receives the 
environment of the parent. The execl e, _execlpe, execve, and _execvpe functions 
let you change the environment for the child process by passing a list of environment 
settings through the envp argument. The envp argument is an array of character 
pointers, each element of which points to a string ending with a null character that 
defines an environment variable. Such a string usually has the following form: 
NAME=value 

where NAME is the name of an environment variable, and value is the string value to 
which the exec function sets that variable. 

Note: Do not enclose the value in double quotation marks. 

The final element of the envp array should be NULL. When envp itself is NULL, 
the child process receives the environment settings of the parent process. 

The exec functions do not preserve signal settings in child processes created by calls 
to exec functions. Calls to exec functions reset the signal settings to the default in 
the child process. 
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Return Value 



The exec functions do not normally return control to the calling process. They are 
equivalent to the corresponding _spawn functions with P_OVERLAY as the value of 
mode flag. If an error occurs, the exec functions return -1 and set errno to one of 
the following values: 


Value 

EACCESS 

EMFILE 

ENOENT 

ENOEXEC 

ENOMEM 


Meaning 

The specified file has a locking or sharing violation. 

There are too many open files. The system must open the specified 
file to tell whether it is an executable file. 

The file or pathname was not found or was specified incorrectly. 
The specified file cannot run or has an incorrect executable file 
format. 

One of the following conditions exists: 

• Not enough storage is available to run the child process. 

• Not enough storage is available for the argument or 
environment strings. 


This example calls four of the eight exec routines. When invoked without 
arguments, the program first runs the code for case PARENT. It then calls execl e() 
to load and run a copy of itself. The instructions for the child are blocked to run 
only if argv[0] and one parameter were passed (case CHILD). In its turn, the child 
runs its own child as a copy of the same program. This sequence is continued until 
four generations of child processes have run. Each of the processes prints a message 
identifying itself. 

#include <stdio.h> 

#include <stdlib.h> 
linclude <process.h> 

#define PARENT 1 

#define CHILD 2 

char *args[3]; 

int main(int argc, char **argv, char **envp) { 
switch(argc) { 

case PARENT: { /* No argument: run a child */ 

printf("Parent process began.\n"); 
execle(argv[0],argv[0],"1",NULL,envp); 

abort(); /* Not executed because parent was overlaid. */ 

} 
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case CHILD: { /* One argument: run a child's child */ 

printf("Chi 1d process %s began.\n", argv[l]); 
if ('1' == *argv[l]) { /* generation one */ 

execl(argv[0], argv[0], "2", NULL); 

abort(); /* Not executed because child was overlaid */ 

} 

if('2' == *argv[l]) { /* generation two */ 

args[0] = argv[0]; 
args[l] = "3"; 
args[2] = NULL; 
execv(argv[0],args); 

abort(); /* Not executed because child was overlaid */ 

} 

if ('3' == *argv[l]) { /* generation three */ 

args[0] = argv[0]; 
args[l] = "4"; 
args[2] = NULL; 

execve(argv[0], args, _environ); 

abort(); /* Not executed because child was overlaid */ 

} 

if (' 4 1 == *argv[l]) /* generation four */ 

printf("Chi 1d process %s", argv[l]); 


printf(" ended.\n"); 
return 55; 

/* The output should be similar to: 

Parent process began. 

Child process 1 began. 

Child process 2 began. 

Child process 3 began. 

Child process 4 began. 

Child process 4 ended. */ 


• “abort — Stop a Program” on page 47 

• “_cwai t — Wait for Child Process” on page 131 

• “exi t — End Program” on page 204 

• “_exit — End Process” on page 205 

• “_spawnl - _spawnvpe — Start and Run Child Processes” on page 548 

• “system — Invoke the Command Processor” on page 639 

• “envp Parameter to main” in the Programming Guide 

• “<process.h>” on page 812 
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exit — End Program 

Format linclude <stdlib.h> /* also in <process.h> */ 

void exit(int status ); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

exi t returns control to the host environment from the program. It first calls all 
functions registered with the atexit function, in reverse order; that is, the last one 
registered is the first one called. See “atexit — Record Program Termination 
Function” on page 62 for more information. It flushes all buffers and closes all open 
files before ending the program. All files opened with tmpf i 1 e are deleted. 

The argument status can have a value from 0 to 255 inclusive or be one of the 
macros EXIT_SUCCESS or EXIT_FAILURE. A status value of EXIT_SUCCESS or 0 
indicates a normal exit; otherwise, another status value is returned. 

Return Value exit returns both control and the value of status to the operating system. 

This example ends the program after flushing buffers and closing any open files if it 
cannot open the file myfile.mjq. 

linclude <stdio.h> 
linclude <stdlib.h> 

FILE *stream; 

int main(void) 

1 

if (NULL == (stream = fopen("myfi1e.mjq", "r"))) { 
perror("Could not open data file"); 
exit(EXIT_FAILURE); 

} 

return 0; 

/•k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-klt-k-k-k-k-klc-k-k-k-k-kie-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-klck-k-k-kick-k-k-k-k-k-k-kick 

The output should be: 

Could not open data file: The file cannot be found. 

i 

• “abort — Stop a Program” on page 47 

• “atexit — Record Program Termination Function” on page 62 

• “_onexit — Record Termination Function” on page 445 

• “_exi t — End Process” on page 205 

• “signal — Handle Interrupt Signals” on page 540 

• “tmpf i 1 e — Create Temporary File” on page 671 

• “<stdlib.h>” on page 816 
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exit — End Process 

Format linclude <stdlib.h> /* also in <process.h> */ 

void _exit(int status ); 

Description Language Level: Extension 

_exit ends the calling process without calling functions registered by _onexit or 
atexit. It also does not flush stream buffers or delete temporary files. You supply 
the status value as a parameter; the value 0 typically means a normal exit. 

Return Value Although _exit does not return a value, the value is available to the waiting parent 
process, if there is one, after the child process ends. If no parent process waits for 
the exiting process, the status value is lost. The status value is available through 
the operating system batch command IF ERRORLEVEL. 

This example calls _exit to end the process. Because _exit does not flush the 
buffer first, the output from the second printf statement will not appear. 

#inc1ude <stdio.h> 

linclude <stdlib.h> /* You can also use <process.h> */ 

char buf [51]; 

int main(void) 

{ 

/* Make sure the standard output stream is line-buffered even if the */ 

/* output is redirected to a file. */ 

if (0 != setvbuf(stdout, buf, _I0LBF, 50)) 

printf("The buffering was not set correctly.\n"); 
printf("This will print out but ...\n"); 
printf("this will not!"); 

_exit(EXIT_FAILURE); 
return 0; 

/**************************************************************************** 

The output should be: 

This will print out but ... 

****************************************************************************/ 

i 

• “abort — Stop a Program” on page 47 

• “atexit — Record Program Termination Function” on page 62 

• “execl - _execvpe — Load and Run Child Process” on page 200 

• “exi t — End Program” on page 204 

• “_onexit — Record Termination Function” on page 445 

• “<process.h>” on page 812 

• “<stdlib.h>” on page 816 
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exp — Calculate Exponential Function 

Format linclude <math.h> 

double exp(double x); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

exp calculates the exponential function of a floating-point argument x (e x , where e 

equals 2.17128128...). 

Return Value If an overflow occurs, exp returns HUGE_VAL. If an underflow occurs, it returns 0. 
Both overflow and underflow set errno to ERANGE. 

This example calculates y as the exponential function of x: 
linclude <math.h> 

int main(void) 

{ 

double x,y; 

x = 5.0; 
y = exp(x); 

printf("exp( %lf ) = %lf\n", x, y); 
return 0; 

/•k-k-klt-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-kit-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k'k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-kick-k-k'k 

The output should be: 
exp( 5.000000 ) = 148.413159 

■k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-kick-k-k j 

} 

• “1 og — Calculate Natural Logarithm” on page 387 

• “log 10 — Calculate Base 10 Logarithm” on page 388 

• “<math.h>” on page 811 
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fabs — Calculate Floating-Point Absolute Value 

Format linclude <math.h> 

double fabs(double x); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fabs calculates the absolute value of the floating-point argument x. 

Return Value fabs returns the absolute value. There is no error return value. 

This example calculates y as the absolute value of x: 

#include <math.h> 

int main(void) 

{ 

double x,y; 

x = -5.6798; 
y = fabs(x); 

printf("fabs( %lf ) = %lf\n", x, y); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

fabs( -5.679800 ) = 5.679800 

****************************************************************************/ 

} 

• “abs — Calculate Integer Absolute Value” on page 48 

• “_cabs — Calculate Absolute Value of Complex Number” on page 78 

• “labs — Calculate Absolute Value of Long Integer” on page 371 

• “<math.h>” on page 811 




Chapter 3. Library Functions 207 



.facos 


facos — Calculate Arccosine 

Format #include <builtin.h> 

double _facos(double x); 


Description Language Level: Extension 

_facos calculates the arccosine of x. This function causes the compiler to emit the 
appropriate 80387 instructions for the calculation of the arccosine. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _facos. 

• You cannot parenthesize a _facos function call, because parentheses specify a 
call to the backing code for the function. 


Return Value facos returns the arccosine of x. 



This example prompts for a value for x. It prints an error message if x is greater than 
1 or less than -1. Otherwise, it assigns the arccosine of x toy. 

#include <bui1tin.h> 

#include <stdio.h> 


#define MAX 1.0 
#define MIN -1.0 


int main(void) 

{ 

double x; 

printf("Enter x:\n"); 
scanf("%lf", &x); 

/* Output error if not in range */ 
if (MAX < x) 

printf("Error: %lf too large for acos.\n", x); 
else if (MIN > x) 

printf("Error: %lf too small for acos.\n", x); 
else 

printf("The arccossine of %1f is %lf.\n", x, _facos(x)); 
return 0; 

/**************************************************************************** 

Assuming you enter: -1.0 

The output should be: 

The arccossine of -1.000000 is 3.141593. 
****************************************************************************/ 

} 
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• “acos — Calculate Arccosine” on page 51 
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• “cos — Calculate Cosine” on page 111 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_fcos — Calculate Cosine” on page 214 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsi ncos — Calculate Sine and Cosine” on page 278 

• “<builtin.h>” on page 801 
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fas in — Calculate Arcsine 

Format linclude <builtin.h> 

double _fasin(double x); 

Description Language Level: Extension 

_fasin calculates the arcsine of x. This function causes the compiler to emit the 
appropriate 80387 instructions for the calculation of arcsine. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fasi n. 

• You cannot parenthesize a _fasin function call, because parentheses specify a 
call to the backing code for the function. 

Return Value _facos returns the arcsine of x. 

This example prompts for a value of x. It prints an error message if x is greater than 
1 or less than -1. Otherwise, it assigns the arcsine of x toy. 

#include <bui1tin.h> 
linclude <stdio.h> 

Idefine MAX 1.0 
Idefine MIN -1.0 

int main(void) 

{ 

double x; 

printf("Enter x:\n"); 
scanf("%lf", &x); 

/* Output error if not in range */ 
if (MAX < x) 

printf("Error: %lf too large for asin.\n", x); 
else if (MIN > x) 

printf("Error: %lf too small for asin.\n“, x); 
else 

printf("The arcsine of %lf is %lf.\n", x, _fasin(x)); 
return 0; 

/**************************************************************************** 

Assuming you enter: 1.0 

The ouput should be: 

The arcsine of 1.000000 is 1.570796. 

****************************************************************************/ 

} 
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• “asi n — Calculate Arcsine” on page 57 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsi n — Calculate Sine” on page 277 

• “_fsi ncos — Calculate Sine and Cosine” on page 278 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “<builtin.h>” on page 801 
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fclose — Close Stream 

Format linclude <stdio.h> 

int fclose(FILE *stream ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fclose closes a stream pointed to by stream. This function flushes all buffers 
associated with the stream before closing it. When it closes the stream, the function 
releases any buffers that the system reserved. When a binary stream is closed, the 
last record in the file is padded with null characters (\0) to the end of the record. 

Return Value fclose returns 0 if it successfully closes the stream, or EOF if any errors were 
detected. 

Note: Once you close a stream with fclose, you must open it again before you can 
use it. 

This example opens a file fclose.dat for reading as a stream; then it closes this file, 
linclude <stdio.h> 

int main(void) 

{ 

FILE *stream; 

stream = fopen("fclose.dat", "r"); 

if (0 != fclose(stream)) /* Close the stream.*/ 

perror("fclose error"); 
else 

printf("File closed successfully.\n"); 
return 0; 

/•k-k-k-k-k-klc-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-kie-k-k'k-k-k-k-k-k-k-k-klck-k-k-k-klck-k-k-kick-k-k-k-k-k-k-kick 

The output should be: 

File closed successfully. 

i 

• “close — Close File Associated with Handle” on page 99 

• “_fcloseal 1 — Close All Open Streams” on page 213 

• “ffl ush — Write Buffer to File” on page 224 

• “fopen — Open Files” on page 243 

• “freopen — Redirect Open Files” on page 268 

• “<stdio.h>” on page 815 
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_fcloseal1 — Close All Open Streams 

Format linclude <stdio.h> 

int _fcloseal1(void); 

Description Language Level: Extension 

_fcloseail closes all open streams, except stdin, stdout, and stderr. It also closes 
and deletes any temporary files created by tmpf i 1 e. 

_ f cl oseal 1 flushes all buffers associated with the streams before closing them. 

When it closes streams, it releases the buffers that the system reserved, but does not 
release user-allocated buffers. 


Return Value 


fcl oseal 1 returns the total number of streams closed, or EOF if an error occurs. 



This example opens a file john for reading as a data stream, and then closes the file. 
It closes all other streams except stdin, stdout, and stderr. 

#include <stdio.h> 


Idefine OUTFILE "temp.out" 


int main(void) 

{ 

FILE *stream; 
int numclosed; 

stream = fopen(OUTFILE, "w"); 
numclosed = _fcloseal1(); 

printf("Number of files closed = %d\n", numclosed); 
remove(OUTFILE); 
return 0; 

/**************************************************************************** 
The output should be: 

Number of files closed = 1 

****************************************************************************/ 

i 



“close — Close File Associated with Handle” on page 99 

“fclose — Close Stream” on page 212 

“ffl ush — Write Buffer to File” on page 224 

“fopen — Open Files” on page 243 

“freopen — Redirect Open Files” on page 268 

“tmpfile — Create Temporary File” on page 671 

“<stdio.h>” on page 815 
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fcos — Calculate Cosine 

Format linclude <builtin.h> 

double _fcos( double x); 

Description Language Level: Extension 

_fcos calculates the cosine of x, where x is expressed in radians. The value of x 
must be less than 2**63. This function causes the compiler to emit the appropriate 
80387 instruction and return only the cosine. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fcos. 

• You cannot parenthesize a _fcos function call, because parentheses specify a call 
to the backing code for the function in the library. 

Return Value _fcos returns the cosine expressed in radians. 

This example calculates y to be the cosine of x. 

#include <bui1tin.h> 
linclude <stdio.h> 

int main(void) 

{ 

double x; 
x = 7.2; 

printf("The cosine of %lf is %lf.\n", x, _fcos(x)); 
return 0; 

/•k-k-klt-k-k-k-k-kle-k-k'k-k-k'k-k-k-k-k-kle-kit'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-kick-k-k-k 

The output should be similar to : 

The cosine of 7.200000 is 0.608351. 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k1<‘k-k-k‘k'k1<‘k-kic-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k'k-k-k-k-k-k-k-k‘k-k'k/ 

} 

• “cos—Calculate Cosine” on page 111 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_facos — Calculate Arccosine” on page 208 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “<builtin.h>” on page 801 
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fcossin — Calculate Cosine and Sine 

Format linclude <builtin.h> 

double _fcossin(double x, double *y ); 


Description Language Level: Extension 

_fcossin calculates the cosine of x, and stores the sine of x in *y. This is faster 
than separately calculating the sine and cosine. Use _fcossin instead of _fsincos 
when you will be using the cosine first, and then the sine. This function causes the 
compiler to emit the FSINCOS 80387 instruction. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fcossi n. 

• You cannot parenthesize a _fcossi n function call, because parentheses specify a 
call to the backing code for the function in the library. 


Return Value fcossin returns the cosine of x. 



This example calculates the cosine of x and stores it in z, and stores the sine of x in 

*y. 

#include <builtin.h> 

#include <stdio.h> 


int main(void) 

{ 

double x, y, z; 

printf("Enter x:\n"); 
scanf("%lf", &x); 

z = _fcossin(x, &y); 

printf("The cosine of %lf is %lf.\n", x, z); 
printf("The sine of %lf is %lf.\n", x, y); 
return 0; 

/**************************************************************************** 
Assuming you enter : 1.0 

The output should be : 

The cosine of 1.000000 is 0.540302. 

The sine of 1.000000 is 0.841471. 

****************************************************************************/ 



“acos — Calculate Arccosine” on page 51 

“asi n — Calculate Arcsine” on page 57 

“cos — Calculate Cosine” on page 111 

“cosh — Calculate Hyperbolic Cosine” on page 112 
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• “_facos — Calculate Arccosine” on page 208 

• “_fasin — Calculate Arcsine” on page 210 

• “_fcos — Calculate Cosine” on page 214 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “_fsi n — Calculate Sine” on page 277 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “<builtin.h>” on page 801 
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fcvt — Convert Floating-Point to String 

Format linclude <stdlib.h> 

char *_fcvt(double value, int ndec, int *decptr, int *signptr ); 

Description Language Level: Extension 

_fcvt converts the floating-point number value to a character string. _fcvt stores 
the digits of value as a string and adds a null character (\0). The ndec variable 
specifies the number of digits to be stored after the decimal point. 

If the number of digits after the decimal point in value exceeds ndec , _fcvt rounds 
the correct digit according to the FORTRAN F format. If there are fewer than ndec 
digits of precision, _fcvt pads the string with zeros. 

A FORTRAN F number has the following format: 


r, 4 + _1_ _i_1_ft, - 



' U LULL • ’ ^ ^ 


_fcvt stores only digits in the string. You can obtain the position of the decimal 
point and the sign of value after the call from decptr and signptr. decptr points 
to an integer value giving the position of the decimal point with respect to the 
beginning of the string. A 0 or negative integer value shows that the decimal point 
lies to the left of the first digit. 

signptr points to an integer showing the sign of value. _fcvt sets the integer to 0 
if value is positive and to a nonzero number if value is negative. 

_fcvt also converts NaN and infinity values to the strings NAN and INFINITY, 
respectively. For more information on NaN and infinity values, see “Infinity and 
NaN Support” on page 33. Warning: For each thread, the _ecvt, _fcvt, and 
_gcvt functions use a single, dynamically allocated buffer for the conversion. Any 
subsequent call that the same thread makes to these functions destroys the result of 
the previous call. 

Return Value _fcvt returns a pointer to the string of digits. Because of the limited precision of 

the double type, no more than 16 decimal digits are significant in any conversion. If 
it cannot allocate memory to perform the conversion, _fcvt returns NULL and sets 
errno to ENOMEM. 
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This example reads in two floating-point numbers, computes their product, and prints 
out only the billions digit of its character representation. At most, 16 decimal digits 
of significance can be expected. The output given assumes the user enters the values 
2000000 and 3000. 

#include <stdio.h> 

#include <stdlib.h> 

#include <math.h> 


int main(void) 

{ 

float x = 2000000; 
float y = 3000; 
double z; 

int w,b,decimal.sign; 
char *buffer; 

z = x *y; 

printf("The product of %e and %e is %g.\n", x, y, z); 

w = 1og10(Tabs(z)) + 1.; 

buffer = _fcvt(z, w, &decimal, &sign); 

b = decimal-10; 

if (b < 0) 

printf("Their product does not exceed one bi11ion.\n"); 
if (b > 15) 

printf("The billions digit of their product is insignificant.\n"); 
if ((b > -1) && (b < 16)) 

printf("The billions digit of their product is %c.\n", buffer[b]); 
return 0; 

/**************************************************************************** 

The output should be: 

The product of 2.0OO0OOe+O6 and 3.O0OO0Oe+O3 is 6e+09. 

The billions digit of their product is 6. 
****************************************************************************/ 



“_ecvt — Convert Floating-Point to Character” on page 192 
“_gcvt — Convert Floating-Point to String” on page 294 
“Infinity and NaN Support” on page 33 
“<stdlib.h>” on page 816 
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fdopen — Associates Input Or Output With File 

Format linclude <stdio.h> 

FILE *fdopen(int handle, char *type ); 

Description Language Level: XPG4, Extension 

fdopen associates an input or output stream with the file identified by handle. The 
type variable is a character string specifying the type of access requested for the 
stream. 

Mode Description 

r Create a stream to read a text file. The file pointer is set to the 

beginning of the file. 

w Create a stream to write to a text file. The file pointer is set to 

the beginning of the file. 

a Create a stream to write, in append mode, at the end of the text 

file. The file pointer is set to the end of the file. 

r+ Create a stream for reading and writing a text file. The file 

pointer is set to the beginning of the file. 

w+ Create a stream for reading and writing a text file. The file 

pointer is set to the beginning of the file. 

a+ Create a stream for reading or writing, in append mode, at the end 

of the text file. The file pointer is set to the end of the file. 

rb Create a stream to read a binary file. The file pointer is set to the 

beginning of the file. 

wb Create a stream to write to a binary file. The file pointer is set to 

the beginning of the file. 

ab Create a stream to write to a binary file in append mode. The file 

pointer is set to the end of the file. 

r+b or rb+ Create a stream for reading and writing a binary file. The file 

pointer is set to the beginning of the file. 

w+b or wb+ Create a stream for reading and writing a binary file. The file 

pointer is set to the beginning of the file. 

a+b or ab+ Create a stream for reading and writing to a binary file in append 

mode. The file pointer is set to the end of the file. 

Warning: Use the w, w+, wb, wb+, and w+b modes with care; they can destroy 
existing files. 
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Return Value 



The specified type must be compatible with the access mode you used to open the 
file. If the file was opened with the 0_APPEND FLAG, the stream mode must be r, 
a, a+, rb, ab, a+b, or ab+. 

When you open a file with a, a+, ab, a+b, or ab+ as the value of type , all write 
operations take place at the end of the file. Although you can reposition the file 
pointer using fseek or rewind, the file pointer always moves back to the end of the 
file before the system carries out any write operation. This action prevents you from 
writing over existing data. 

When you specify any of the types containing +, you can read from and write to the 
file, and the file is open for update. However, when switching from reading to 
writing or from writing to reading, you must include an intervening fseek, fsetpos, or 
rewind operation. You can specify the current file position with fseek. 

In accessing text files, carriage-return line-feed (CR-LF) combinations are translated 
into a single line feed (LF) on input; LF characters are translated to CR-LF 
combinations on output. Accesses to binary files suppress all of these translations. 
(See “Stream Processing” in the Programming Guide for the differences between text 
and binary streams.) 

If fdopen returns NULL, use close to close the file. If fdopen is successful, you must 
use fclose to close the stream and file. 

Note: In earlier releases of C Set ++, fdopen began with an underscore (_fdopen). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _fdopen to fdopen for you. 

fdopen returns a pointer to a file structure that can be used to access the open file. 

A NULL pointer return value indicates an error. 

This example opens the file sample.dat and associates a stream with the file using 
fdopen. It then reads from the stream into the buffer. 
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#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl.h> 

#include <string.h> 

int main(void) 

{ 

long length; 
int fh; 

char buffer[20]; 

FILE *fp; 

memset(buffer, '\G', 20); /* Initialize buffer*/ 

printf("\nCreating sample.dat.\n"); 
system("echo Sample Program > sample.dat"); 
if (-1 == (fh = open("sample.dat", 0_RDWR|0_APPEND))) { 
perror("Unable to open sample.dat"); 
return EXIT_FAILURE; 

} 

if (NULL == (fp = fdopen(fh, "r"))) { 
perror("fdopen failed"); 
close(fh); 

return EXIT_FAILURE; 

} 

if (7 != fread(buffer, 1, 7, fp)) { 
perror("fread failed"); 
fclose(fp); 
return EXIT_FAILURE; 

} 

printf("Successfully read from the stream the fol1 owing:\n%sAn", buffer); 
fclose(fp); 
return 0; 

/**************************************************************************** 
The output should be: 

Creating sample.dat. 

Successfully read from the stream the following: 

Sample . 

****************************************************************************/ 

} 


• “close — Close File Associated with Handle” on page 99 

• “creat — Create New File” on page 115 

• “fclose — Close Stream” on page 212 

• “fopen — Open Files” on page 243 

• “fseek — Reposition File Position” on page 273 

• “fsetpos — Set File Position” on page 275 

• “open — Open File” on page 447 

• “rewi nd — Adjust Current File Position” on page 497 

• “_sopen — Open Shared File” on page 545 

• “<stdio.h>” on page 815 
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feof — Test End-of-File Indicator 

Format linclude <stdio.h> 

int feof (FILE *stream ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

feof indicates whether the end-of-file flag is set for the given stream. The 
end-of-file flag is set by several functions to indicate the end of the file. The 
end-of-file flag is cleared by calling rewind, fsetpos, fseek, or clearerr for this 
stream. 

Return Value feof returns a nonzero value if and only if the EOF flag is set; otherwise, it returns 
0 . 

This example scans the input stream until it reads an end-of-file character, 
linclude <stdio.h> 

int main(void) 

{ 

char inp_char; 

FILE *stream; 

stream = fopen("feof.dat", "r"); 

/* scan an input stream until an end-of-file character is read */ 

while (0 == feof(stream)) { 

fscanf(stream, "%c", &inp_char); 
printf("<x%x> ", inp_char); 

} 

fclose(stream); 
return 0; 

/**************************************************************************** 

If feof.dat contains : abc defgh 

The output should be: 

<x61> <x62> <x63> <x20> <x64> <x65> <x66> <x67> <x68> 
****************************************************************************/ 

} 

• “clearerr — Reset Error Indicators.” on page 94 

• “terror — Test for Read/Write Errors” on page 223 

• “fseek — Reposition File Position” on page 273 

• “fsetpos — Set File Position” on page 275 

• “perror — Print Error Message” on page 459 

• “rewi nd — Adjust Current File Position” on page 497 

• “<stdio.h>” on page 815 
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ferror — Test for Read/Write Errors 

Format linclude <stdio.h> 

int ferror(FILE *stream ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

ferror tests for an error in reading from or writing to the given stream. If an error 
occurs, the error indicator for the stream remains set until you close stream , call 
rewind, or call clearerr. 


Return Value The ferror function returns a nonzero value to indicate an error on the given 
stream. A return value of 0 means no error has occurred. 



This example puts data out to a stream and then checks that a write error has not 
occurred. 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

FILE *stream; 

char *string = "Important information"; 

stream = fopen("ferror.dat", "w"); 
fprintf(stream, "%s\n", string); 
if (ferror(stream)) { 

printf("write error\n"); 
cl earerr(stream); 
return EXIT_FAILURE; 

} 

el se 

printf("Data written to a file successfully.\n"); 
if (fclose(stream)) 

perror("fclose error"); 
return 0; 

/**************************************************************************** 
The output should be: 

Data written to a file successfully. 

****************************************************************************/ 

i 



“cl earerr — Reset Error Indicators.” on page 94 

“feof — Test End-of-File Indicator” on page 222 

“fopen — Open Files” on page 243 

“perror — Print Error Message” on page 459 

“strerror — Set Pointer to Runtime Error Message” on page 579 

“_strerror — Set Pointer to System Error String” on page 580 

“<stdio.h>” on page 815 
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fflush — Write Buffer to File 

Format linclude <stdio.h> 

int fflush(FILE *stream ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fflush causes the system to empty the buffer associated with the specified output 
stream , if possible. If the stream is open for input, fflush undoes the effect of any 
ungetc function. The stream remains open after the call. 

If stream is NULL, the system flushes all open streams. 

Note: The system automatically flushes buffers when you close the stream, or when 
a program ends normally without closing the stream. 

Return Value fflush returns the value 0 if it successfully flushes the buffer. It returns EOF if an 
error occurs. 

This example flushes a stream buffer, 
linclude <stdio.h> 

int main(void) 

{ 

FILE *stream; 

stream = fopen("myfile.dat", "w"); 
fprintf(stream, "He!1o world"); 
fflush(stream); 
fclose(stream); 
return 0; 

} 

• “fclose — Close Stream” on page 212 

• “_fl ushal 1 — Write Buffers to Files” on page 240 

• “setbuf — Control Buffering” on page 524 

• “ungetc — Push Character onto Input Stream” on page 721 

• “<stdio.h>” on page 815 
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fgetc — Read a Character 

Format linclude <stdio.h> 

int fgetc(FILE *stream); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fgetc reads a single unsigned character from the input stream at the current position 
and increases the associated file pointer, if any, so that it points to the next character. 

Note: fgetc is identical to getc but is always implemented as a function call; it is 
never replaced by a macro. 

Return Value fgetc returns the character read as an integer. An EOF return value indicates an 

error or an end-of-file condition. Use feof or ferror to determine whether the EOF 
value indicates an error or the end of the file. 

This example gathers a line of input from a stream. 

#inc1ude <stdio.h> 

Idefine MAX_LEN 80 

int main(void) 

{ 

FILE *stream; 
char buffer[MAX_LEN+l]; 
int i,ch; 

stream = fopen("myfile.dat", "r"); 

for (i =0; (i < (sizeof(buffer)-l) && ((ch = fgetc(stream)) != EOF) && 

(ch != 1 \n 1 )); i++) 
buffer[i] = ch; 
buffer[i] = 1 \0'; 
if (fclose(stream)) 

perror("fclose error"); 
printf("The input line was : %s\n", buffer); 
return 0; 

/**************************************************************************** 

If myfile.dat contains: one two three 

The output should be: 

The input line was : one two three 

****************************************************************************/ 

} 

• “_fgetchar — Read Single Character from stdin" on page 227 

• “feof — Test End-of-File Indicator” on page 222 

• “ferror — Test for Read/Write Errors” on page 223 

• “fputc — Write Character” on page 252 

• “getc - getchar — Read a Character” on page 296 
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• “_getch - _getche — Read Character from Keyboard” on page 298 

• “<stdio.h>” on page 815 
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fgetchar — Read Single Character from stdin 

Format linclude <stdio.h> 

int _fgetchar(void); 

Description Language Level: Extension 

_fgetchar reads a single character from the stdin stream. It is equivalent to the 
following fgetc call: 

fgetc(c, stdin); 

For portability, use the ANSI/ISO fgetc function instead of _fgetchar. 

Return Value _fgetchar returns the character read. A return value of EOF indicates an error or 
end-of-file position. Use feof or terror to tell whether the return value indicates an 
error or an end-of-file position. 

This example gathers a line of input from stdin using _fgetchar: 

#inc1ude <stdio.h> 

int main(void) 

{ 

char buffer[81]; 
int i,ch; 

printf ("Please input a line of characters.. An"); 

for (i =0; (i < 80) && ((ch = _fgetchar()) != EOF) && (ch 1 = An'); i++) 
bufferfi] = ch; 
bufferfi] = 1 \0'; 

printf("The input line was : %s\n", buffer); 
return 0; 

/**************************************************************************** 

The output should be: 

Please input a line of characters... 

This is a simple program. 

The input line was : This is a simple program. 
****************************************************************************/ 

} 

• “feof — Test End-of-File Indicator” on page 222 

• “ferror — Test for Read/Write Errors” on page 223 

• “fgetc — Read a Character” on page 225 

• “_fputchar — Write Character” on page 254 

• “getc - getchar — Read a Character” on page 296 

• “_getch - _getche — Read Character from Keyboard” on page 298 

• “<stdio.h>” on page 815 
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fgetpos — Get File Position 

Format linclude <stdio.h> 

int fgetpos(FILE *stream, fpos_t *pos); 

Description Language Level: ANSI, SAA, XPG4 

fgetpos stores the current position of the file pointer associated with stream into the 
object pointed to by pos. The value pointed to by pos can be used later in a call to 
fsetpos to reposition the stream. 

Note: For buffered text streams, fgetpos returns an incorrect file position if the file 
contains new-line characters instead of carriage-return line-feed combinations. Your 
file would only contain new-line characters if you previously used it as a binary 
stream. To avoid this problem, either continue to process the file as a binary stream, 
or use unbuffered I/O operations. 


Return Value fgetpos returns 0 if successful. On error, fgetpos returns nonzero and sets errno to 
a nonzero value. 



This example opens the file myfile.dat for reading and stores the current file pointer 
position into the variable pos. 
linclude <stdio.h> 


FILE *stream; 


int main(void) 

{ 

int retcode; 
fpos_t pos; 

stream = fopen("myfile.dat", "rb"); 

/* The value returned by fgetpos can be used by fsetpos */ 

/* to set the file pointer if 'retcode' is 0 */ 

if ( 0 == (retcode = fgetpos(stream, &pos)) ) 

printf("Current position of file pointer found.\n"); 
fcl ose(stream); 
return 0; 


/**************************************************************************** 


If myfile.dat exists, the output should be: 


Current position of file pointer found. 


ic-k-k-k-kicic-kic-k'kic-k'k'k-k-k-kic-k'k-k'k-kic-kii-k-kicie-kick'kick'k-k-k-k-k-k-k-k-k'kickicick-k'k-k-kick'k-k-k-kick-kick-k-kick-k-k-kick 

) 


i 



“fseek — Reposition File Position” on page 273 
“fsetpos — Set File Position” on page 275 
“ftel 1 — Get Current Position” on page 283 
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• “<stdio.h>” on page 815 
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fgets — Read a String 

Format linclude <stdio.h> 

char *fgets (char *string, int n, FILE *stream ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

fgets reads characters from the current stream position up to and including the first 
new-line character (\n), up to the end of the stream, or until the number of characters 
read is equal to n-1, whichever comes first, fgets stores the result in string and 
adds a null character (\0) to the end of the string. The string includes the new-line 
character, if read. If n is equal to 1, the string is empty. 


Return Value fgets returns a pointer to the string buffer if successful. A NULL return value 
indicates an error or an end-of-file condition. Use feof or terror to determine 
whether the NULL value indicates an error or the end of the file. In either case, the 
value of the string is unchanged. 



This example gets a line of input from a data stream. The example reads no more 
than MAX_LEN - 1 characters, or up to a new-line character, from the stream. 

#include <stdio.h> 


#define MAX LEN 100 


int main(void) 

{ 

FILE *stream; 

char 1ine[MAX_LEN],*result; 

stream = fopen("myfile.dat", "rb"); 
if ((result = fgets(line, MAX_LEN, stream)) != NULL) 
printf("The string is %s\n“, result); 
if (fclose(stream)) 

perror("fclose error"); 
return 0; 


/**************************************************************************** 
If myfile.dat contains: This is my data file. 

The output should be: 

The string is This is my data file. 

****************************************************************************/ 

1 



“feof — Test End-of-File Indicator” on page 222 
“ferror — Test for Read/Write Errors” on page 223 
“fputs — Write String” on page 255 
“gets — Read a Line” on page 309 
“puts — Write a String” on page 473 
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• “<stdio.h>” on page 815 
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fgetwc — Read Wide Character from Stream 

Format linclude <stdio.h> 

linclude <wchar.h> 
wint_t fgetwc(FILE *stream ); 

Description Language Level: ANSI 93 

fgetwc reads the next multibyte character from the input stream pointed to by 
stream , converts it to a wide character, and advances the associated file position 
indicator for the stream (if defined). 

The behavior of fgetwc is affected by the LC_CTYPE category of the current locale. 
If you change the category between subsequent read operations on the same stream, 
undefined results can occur. 

Using non-wide-character functions with fgetwc on the same stream results in 
undefined behavior. 


After calling fgetwc, flush the buffer or reposition the stream pointer before calling a 
write function for the stream, unless EOF has been reached. After a write operation 
on the stream, flush the buffer or reposition the stream pointer before calling fgetwc. 


Return Value fgetwc returns the next wide character that corresponds to the multibyte character 
from the input stream pointed to by stream. If the stream is at EOF, the EOF 
indicator for the stream is set and fgetwc returns WEOF. 


If a read error occurs, the error indicator for the stream is set and fgetwc returns 
WEOF. If an encoding error occurs (an error converting the multibyte character into 
a wide character), fgetwc sets errno to EILSEQ and returns WEOF. 


Use terror and feof to distinguish between a read error and an EOF. EOF is only 
reached when an attempt is made to read past the last byte of data. Reading up to 
and including the last byte of data does not turn on the EOF indicator. 



This example opens a file, reads in each wide character using fgetwc, and prints out 
the characters. 
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#include <stdio.h> 

#include <wchar.h> 

#include <errno.h> 

int main(void) 

{ 

FILE *stream; 
wint_t wc; 

if (NULL == (stream = fopen("fgetwc.dat", "r"))) { 
printf("Unable to open: \"fgetwc.dat\"\n"); 
exit(l); 

} 


errno = 0; 

while (WEOF != (wc = fgetwc(stream))) 
printf("wc = %lc\n", wc); 

if (EILSEQ == errno) { 

printf("An invalid wide character was encountered.\n"); 
exit(l); 

} 

fclose(stream); 
return 0; 

/**************************************************************************** 
Assuming the file fgetwc.dat contains: 

Hello world! 

The output should be similar to: 

wc = H 
wc = e 
wc = 1 
wc = 1 
wc = o 

****************************************************************************/ 

• “fgetc — Read a Character” on page 225 

• “_fgetchar — Read Single Character from stdin” on page 227 

• “fgetws — Read Wide-Character String from Stream” on page 234 

• “fputwc — Write Wide Character” on page 257 

• “_getch - _getche — Read Character from Keyboard” on page 298 

• “<stdio.h>” on page 815 

• “<wchar.h>” on page 821 
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fgetws — Read Wide-Character String from Stream 

Format linclude <stdio.h> 

linclude <wchar.h> 

wchar_t *fgetws(wchar_t *wcs , int n, FILE *stream ); 

Description Language Level: ANSI 93, XPG4 

fgetws reads wide characters from the stream into the array pointed to by wcs. At 
most, n - 1 wide characters are read, fgetws stops reading characters after WEOF, 
or after it reads a new-line wide character (which is retained). It adds a null wide 
character immediately after the last wide character read into the array. 

fgetws advances the file position unless there is an error. If an error occurs, the file 
position is undefined. 

The behavior of fgetws is affected by the LC_CTYPE category of the current locale. 
If you change the category between subsequent read operations on the same stream, 
undefined results can occur. 

Using non-wide-character functions with fgetws on the same stream results in 
undefined behavior. 

After calling fgetws, flush the buffer or reposition the stream pointer before calling a 
write function for the stream, unless WEOF has been reached. After a write 
operation on the stream, flush the buffer or reposition the stream pointer before 
calling fgetws. 

Return Value If successful, fgetws returns a pointer to the wide-character string wcs. If WEOF 
is encountered before any wide characters have been read into wcs, the contents of 
wcs remain unchanged and fgetws returns a null pointer. If WEOF is reached after 
data has already been read into the string buffer, fgetws returns a pointer to the 
string buffer to indicate success. A subsequent call would return NULL because 
WEOF would be reached without any data being read. 

If a read error occurs, the contents of wcs are indeterminate and fgetws returns 
NULL. If an encoding error occurs (in converting a wide character to a multibyte 
character), fgetws sets errno to EILSEQ and returns NULL. 

If n equals 1, the wcs buffer has only room for the terminating null character and 
nothing is read from the stream. (Such an operation is still considered a read 
operation, so it cannot immediately follow a write operation unless the buffer is 
flushed or the stream pointer repositioned first.) 
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If n is greater than 1, fgetws fails only if an I/O error occurs or if WEOF is reached 
before data is read from the stream. Use terror and feof to distinguish between a 
read error and a WEOF. WEOF is only reached when an attempt is made to read 
past the last byte of data. Reading up to and including the last byte of data does not 
turn on the WEOF indicator. 

This example opens a file, reads in the file contents using fgetws, then prints the file 
contents. 

#include <errno.h> 

#include <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

FILE *stream; 
wchar_t wcs[100]; 

if (NULL == (stream = fopen("fgetws.dat", "r"))) { 
printf("Unable to open: \"fgetws.dat\"\n"); 
exit(l); 

} 


errno = 0; 

if (NULL == fgetws(wcs, 100, stream)) { 
if (EILSEQ == errno) { 

printf("An invalid wide character was encountered.\n"); 
exit(l); 

} 

else if (feof(stream)) 

printf("End of file reached.\n"); 
el se 

perror("Read error.\n"); 

} 

printf("wcs = \"%ls\"\n", wcs); 
fclose(stream); 
return 0; 

/**************************************************************************** 
Assuming the file fgetws.dat contains: 

This test string should not return -1 

The output should be similar to: 

wcs = "This test string should not return -1" 
****************************************************************************/ 

} 


• “fgets — Read a String” on page 230 

• “fgetwc — Read Wide Character from Stream” on page 232 

• “fputws — Write Wide-Character String” on page 259. 

• “<stdio.h>” on page 815 

• “<wchar.h>” on page 821 
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_fi1 elength 

Format 

Description 

Return Value 



— Determine File Length 

#include <io.h> 

long _fi1 elength(int handle ); 

Language Level: Extension 

_filei ength returns the length, in bytes, of the file associated with handle. The 
length of the file will be correct even if you have the handle opened and have 
appended data to the file. 


A return value of -1L indicates an error, and errno is set to one of the following 
values: 

Value Meaning 

EBADF The file handle is incorrect or the mode specified does not match the 

mode you opened the file with. 

EOS2ERR The call to the operating system was not successful. 

This example opens a file and tries to determine the current length of the file using 
_fi 1 el ength. 

#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl,h> 

int main(void) 

{ 

long length; 
int fh; 

printf("\nCreating sample.dat.\n"); 
system("echo Sample Program > sample.dat"); 
if (-1 == (fh = open("sample.dat", 0_RDWR|0_APPEND))) { 
printf("Unable to open sample.dat.\n"); 
return EXIT_FAILURE; 

} 

if (-1 == (length = _filelength(fh))) { 

printf("Unable to determine length of sample.dat.\n"); 
return EXIT_FAILURE; 

} 

printf("Current length of sample.dat is %d.\n", length); 
close(fh); 
return 0; 

/**************************************************************************** 

The output should be: 

Creating sample.dat. 

Current length of sample.dat is 17. 

****************************************************************************/ 
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• “_chsi ze — Alter Length of File” on page 92 

• “_eof — Determine End of File” on page 197 

• “<io.h>” on page 804 
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fileno — Determine File Handle 

Format linclude <stdio.h> 

int fileno(FILE *stream ); 

Description Language Level: XPG4, Extension 

fileno determines the file handle currently associated with stream. 

Note: In earlier releases of C Set ++, fileno began with an underscore (_fileno). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _fileno to fileno for you. 

Return Value f i 1 eno returns the file handle. If the function fails, the return value is -1 and the 
errno variable may be set to one of the following values: 

Value Meaning 

ENULLFCB The input stream is NULL. 

EBADTYPE The input stream file is not a stream file. 

The result is undefined if stream does not specify an open file. 

This example determines the file handle of the stderr data stream, 
linclude <stdio.h> 

int main(void) 

{ 

int result; 

result = OxFFFF & fileno(stderr); 

printf("The file handle associated with stderr is %d.\n", result); 
return 0; 

/•k-k-kle-k-kle-k-kle-k-k'k-k-kle-k-k'k-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k'k-k'k-k-k'k 

The output should be: 

The file handle associated with stderr is 2. 

■k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-kle-k-k-k-k-k-k-k-k'k-k-klck-k-k-kit/ 

1 

• “dup — Associate Second Handle with Open File” on page 186 

• “dup2 — Associate Second Handle with Open File” on page 189 

• “fopen — Open Files” on page 243 

• “freopen — Redirect Open Files” on page 268 

• “i satty — Test Handle for Character Device” on page 352 

• “open — Open File” on page 447 

• “<stdio.h>” on page 815 
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floor — Integer <= Argument 

Format linclude <math.h> 

double floor(double x); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

floor calculates the largest integer that is less than or equal to x. 


Return Value floor returns the floating-point result as a double value. 
The result of floor cannot have a range error. 



This example assigns y value of the largest integer less than or equal to 2.8 and z the 
value of the largest integer less than or equal to -2.8. 

#include <math.h> 

int main(void) 

{ 

double y,z; 


y = floor(2.8); 
z = f1oor(-2.8); 

printf("floor( 2.8 ) = %lf\n", y); 
printf("floor( -2.8 ) = %lf\n", z); 
return 0; 


/**************************************************************************** 
The output should be: 


floor( 2.8 ) = 2.000000 
floor( -2.8 ) = -3.000000 

****************************************************************************/ 

} 



“cei 1 — Find Integer >= Argument” on page 84 
“fmod — Calculate Floating-Point Remainder” on page 242 
“<math.h>” on page 811 
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_flushal1 - 

Format 

Description 

Return Value 



Write Buffers to Files 

linclude <stdio.h> 
int _flushal1(void); 


Language Level: Extension 

_f 1 ushal 1 causes the system to write to file the contents of all buffers associated 
with open output streams (including stdin, stdout, and stderr). It clears all buffers 
associated with open input streams of their current contents. The next read operation, 
if there is one, reads new data from the input files into the buffers. All streams 
remain open after the call. 

For portability, use the ANSI/ISO function ffl ush instead of _f 1 ushal 1. 


_f 1 ushal 1 returns the number of open streams of input and output. If an error 
occurs, _fl ushal 1 returns EOF. 

In this example, _f 1 ushal 1 completes any pending input or output on all streams by 
flushing all buffers. 

#include <stdio.h> 

int main(void) 

{ 

int i.numflushed; 
char buffer1[5] = { 1,2,3,4 }; 
char buffer2[5] = { 5,6,7,8 }; 
char *filel = "filel.dat"; 
char *file2 = "file2.dat"; 

FILE *streaml,*stream2; 

streaml = fopen(filel, "a+"); 
stream2 = fopen(file2, "a+"); 
for (i = 0; i <= sizeof(bufferl); i++) { 
fputc(bufferl[i], streaml); 
fputc(buffer2[i], stream2); 

} 

numflushed = _flushal1(); /* all streams flushed */ 

printf("Number of files flushed = %d\n", numflushed); 

fcl ose(streaml); 

fclose(stream2); 

return 0; 

/•k-k-klt-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-kle-k-kle-k-k'k-k-k-k-k-k'k-kit'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-kick-k-k'k-k-k'k-k-klck-k-k 

The output should be: 

Number of files flushed = 5 

■k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-kie-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k/ 

} 
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• “close — Close File Associated with Handle” on page 99 

• “fclose — Close Stream” on page 212 

• “ffl ush — Write Buffer to File” on page 224 

• “<stdio.h>” on page 815 
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fmod — Calculate Floating-Point Remainder 

Format linclude <math.h> 

double fmod(double x, double y); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fmod calculates the floating-point remainder of x/y. The absolute value of the result 
is always less than the absolute value ofy. The result will have the same sign as x. 


Return Value fmod returns the floating-point remainder of x/y. If y is zero or if x/y causes an 
overflow, fmod returns 0. 



This example computes z as the remainder of x/y; here, x/y is -3 with a remainder of 
- 1 . 

#include <math.h> 


int main(void) 

{ 

double x,y,z; 


x = -10.0; 
y = 3.0; 
z = fmod(x, y); 

printf ("fmod( %lf, %lf) = %lf\n", 
return 0; 


x, y, 


z); 


/* z = -1.0 */ 



/•k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k-k-k-k‘k-k-k-k-k-k-k 

The output should be: 

fmod( -10.000000, 3.000000) = -1.000000 

-k , k-k1<‘k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k1e-k-k‘k'k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k/ 

} 

• “cei 1 — Find Integer >= Argument” on page 84 

• “fabs — Calculate Floating-Point Absolute Value” on page 207 

• “f 1 oo r — Integer <= Argument” on page 239 

• “<math.h>” on page 811 
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fopen — Open Files 

Format linclude <stdio.h> 

FILE *fopen(const char *filename, const char *mode); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fopen opens the file specified by filename, mode is a character string specifying the 
type of access requested for the file. The mode variable contains one positional 
parameter followed by optional keyword parameters. 

The possible values for the positional parameters are: 

Mode Description 

r Open a text file for reading. The file must exist, 

w Create a text file for writing. If the given file exists, its contents 

are destroyed. 

a Open a text file in append mode for writing at the end of the file, 

fopen creates the file if it does not exist. 

r+ Open a text file for both reading and writing. The file must exist. 

w+ Create a text file for both reading and writing. If the given file 

exists, its contents are destroyed. 

a+ Open a text file in append mode for reading or updating at the end 

of the file, fopen creates the file if it does not exist, 
rb Open a binary file for reading. The file must exist, 

wb Create an empty binary file for writing. If the file exists, its 

contents are destroyed. 

ab Open a binary file in append mode for writing at the end of the 

file, fopen creates the file if it does not exist, 
r+b or rb+ Open a binary file for both reading and writing. The file must 

exist. 

w+b or wb+ Create an empty binary file for both reading and writing. If the 

file exists, its contents will be destroyed. 

a+b or ab+ Open a binary file in append mode for writing at the end of the 

file, fopen creates the file if it does not exist. 

Warning: Use the w, w+, wb, w+b, and wb+ parameters with care; data in existing 
files of the same name will be lost. 

Text files contain printable characters and control characters organized into lines. 

Each line ends with a new-line character, except for the last line, which does not 
require one. The system may insert or convert control characters in an output text 
stream. 
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Note: Data output to a text stream may not compare as equal to the same data on 
input. 

Binary files contain a series of characters. For binary files, the system does not 
translate control characters on input or output. 

When you open a file with a, a+, ab, a+b or ab+ mode, all write operations take place 
at the end of the file. Although you can reposition the file pointer using fseek or 
rewind, the write functions move the file pointer back to the end of the file before 
they carry out any operation. This action prevents you from overwriting existing 
data. 

When you specify the update mode (using + in the second or third position), you can 
both read from and write to the file. However, when switching between reading and 
writing, you must include an intervening positioning function such as fseek, fsetpos, 
rewind, or fflush. Output may immediately follow input if the end-of-file was 
detected. 

The keyword parameters are: 

bl ksize=value Specifies the maximum length, in bytes, of a physical block of 
records. For fixed-length records, the maximum size is 32760 
bytes. For variable-length records, the maximum is 32756. The 
default buffer size is 4096 bytes. 

1 reel = value Specifies the length, in bytes, for fixed-length records and the 

maximum length for variable-length records. For fixed-length 
records, the maximum length is 32760 bytes. For variable-length 
records, the maximum is 32756. If the value of LRECL is larger 
than the value of BLKSIZE, the LRECL value is ignored. 

recfm=value value can be: 

F fixed-length, unblocked records 

V variable-length, unblocked records 

The default for the VisualAge C++ compiler is fixed-length record 
format. 

typ e=value value can be: 

memory This parameter identifies this file as a memory file that is 
accessible only from C programs. This is the default. If you want 
to use a memory file, you must compile with the /Sv option. 

The VisualAge C++ compiler does not support record I/O. 
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fopen generally fails if parameters are mismatched. 

The file attributes can be altered only if the open mode specified with the fopen 
function is one of the write modes (w, w+, wb, or wb+). The system deletes the 
existing file and creates a new file with the attributes specified in fopen. 

Return Value fopen returns a pointer to a file structure that can be used to access the open file. A 
NULL pointer return value indicates an error. 

This example attempts to open a file for reading. 

#inc1ude <stdio.h> 

int main(void) 

{ 

FILE *stream; 

if (NULL == (stream = fopen("myfile.dat", "r"))) 
printf("Could not open data file\n"); 
el se 

fclose(stream); 

/* The following call opens a fixed record length file */ 

/* for reading and writing in record mode. */ 

if (NULL == (stream = fopen("myfile.dat", 

"rb+, lrecl=80, blksize=240, recfm=f, type=record"))) 
printf("Could not open data fi1e\n"); 
el se 

fclose(stream); 
return 0; 

/**************************************************************************** 

The output should be: 

Could not open data file 

****************************************************************************/ 

i 

• “creat — Create New File” on page 115 

• “fclose — Close Stream” on page 212 

• “ffl ush — Write Buffer to File” on page 224 

• “fread — Read Items” on page 261 

• “freopen — Redirect Open Files” on page 268 

• “open — Open File” on page 447 

• “_sopen — Open Shared File” on page 545 

• “fseek — Reposition File Position” on page 273 

• “fsetpos — Set File Position” on page 275 

• “fwri te — Write Items” on page 289 

• “rewi nd — Adjust Current File Position” on page 497 

• “<stdio.h>” on page 815 
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fpatan — Calculate Arctangent 

Format #include <builtin.h> 

double _fpatan(double x ); 

Description Language Level: Extension 

_fpatan calculates the arctangent of x, which is a value in radians between -n /2 and 
jt/2. This function causes the compiler to emit the appropriate 80387 instruction for 
the calculation of arctangent. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fpatan. 

• You cannot parenthesize a _fpatan function call, because parentheses specify a 
call to the backing code for the function. 


Return Value This function returns the arctangent of x. 



This example calculates the arctangent of x. 

#include <bui1tin.h> 

#include <stdio.h> 

int main(void) 

{ 

double x; 


x = 0.45; 

printf("The arctangent of %lf is %lf.\n", 
return 0; 


x, _fpatan(x)); 


j •k-k-k-k-k-k-k-k-kle-k-k'k-k-k-k-k-k-k-k-k'k-kit'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k 

The output should be : 


The arctangent of 0.450000 is 0.422854. 

■k , k-k-k-k-k-k‘k-k1<‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k'k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k'k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k1</ 



“atan - atan2 — Calculate Arctangent” on page 61 

“_fptan — Calculate Tangent” on page 251 

“tan — Calculate Tangent” on page 645 

“tanh — Calculate Hyperbolic Tangent” on page 646 

“<builtin.h>” on page 801 


246 VisualAge C++ C Library Reference 





fpreset 


_fpreset — 

Format 

Description 


Return Value 



Reset Floating-Point Unit 

#include <float.h> 
void _fpreset(void); 

Language Level: Extension 

_fpreset resets the floating-point unit to the default state that the math library 
requires to function correctly. The value of this default state may change between 
releases of VisualAge C++. You can determine the default state by calling _fpreset 
and then calling _control87 with 0 as the parameter. 

This function is often used within signal handlers. If a program traps floating-point 
error signals (SIGFPE) with signal, the program can safely recover from floating-point 
errors by calling longjmp. For more information on signal handlers, see “Signal and 
OS/2 Exception Handling” the Programming Guide. 

_fpreset resets the floating-point unit of the current thread only. It does not affect 
any other threads that may be processing. 

There is no return value. 

This example establishes the function fphandler as a floating-point error handler. 

The main program produces a floating-point error, which causes control to be passed 
to fphandler. The fphandler function calls _fpreset to reset the floating-point unit, 
and then returns to main. 

#include <stdio.h> 

#include <stdlib.h> 

#include <signal ,h> 

#inc1ude <setjmp.h> 

#include <float.h> 

jmp_buf mark; 
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void fphandler(int sig) 

{ 

printf("Floating point signal = %d\n", sig); 

_fpreset(); /* Reinitialize floating-point package */ 

longjmp(mark, -1); 

} 


int main(void) 

{ 

double a = 1.0,b = 0.0,c; 

if (SIG_ERR s= signal(SIGFPE, fphandler)) 
return EXIT_FAILURE; 
if (0 == setjmp(mark)) { 

c = a/b; /* generate floating-point error */ 

printf("Should never get here\n"); 

} 

printf("Recovered from floating-point error\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

Floating point signal = 3 
Recovered from floating-point error 

****************************************************************************/ 

} 



“_cl ear87 — Clear Floating-Point Status Word” on page 95 
“_control87 — Set Floating-Point Control Word” on page 109 
“longjmp — Restore Stack Environment” on page 389 
“signal — Handle Interrupt Signals” on page 540 
“_status87 — Get Floating-Point Status Word” on page 563 
“<float.h>” on page 803 
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fprintf — Write Formatted Data to a Stream 

Format linclude <stdio.h> 

int fprintf(FILE *stream, const char *format-string, argument-list ); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

fprintf formats and writes a series of characters and values to the output stream. 
fprintf converts each entry in argument-list , if any, and writes to the stream 
according to the corresponding format specification in the format-string. 

The format-string has the same form and function as the format-string argument 
for printf. See “printf — Print Formatted Characters” on page 461 for a 
description of the format-string and the argument list. 

In extended mode, fprintf also converts floating-point values of NaN and infinity to 
the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 

If you specify a null string for the %s or %ls format specifier, fprintf prints (null). 
(In previous releases of C Set ++, printf produced no output for a null string.) 


Return Value fprintf returns the number of bytes printed or a negative value if an output error 
occurs. 



This example sends a line of asterisks for each integer in the array count to the file 
myf i 1 e. The number of asterisks printed on each line corresponds to an integer in the 
array. 


#include <stdio.h> 


int count[10] = { 1, 5, 8, 3, 0, 3, 5, 6, 8, 10 } ; 


int main(void) 

{ 

int i,j ; 

FILE *stream; 
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stream = fopen("myfile.dat", "w"); 

/* Open the stream for writing 
for (i = 0; i < sizeof(count)/sizeof(count[0]); i++) { 
for (j = 0; j < countfi]; j++) 
fprintf(stream, 

/* Print asterisk 
fprintf(stream, "\n"); 

/* Move to the next line 


*/ 


*/ 


*/ 


fclose(stream); 
return 0; 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

The output data file myfile.dat should contain: 


* 

kkkkkkkk 

*** 

*** 

kkkkk 

kkkkkk 

kkkkkkkk 

kkkkkkkkkk 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

) 



“_cpri ntf — Print Characters to Screen” on page 113 

“fscanf — Read Formatted Data” on page 271 

“printf — Print Formatted Characters” on page 461 

“spri ntf — Print Formatted Data to Buffer” on page 554 

“vfpri ntf — Print Argument Data to Stream” on page 739 

“vpri ntf — Print Argument Data” on page 741 

“vspri ntf — Print Argument Data to Buffer” on page 743 

“vswprintf — Format and Write Wide Characters to Buffer” on page 745 

“Infinity and NaN Support” on page 33 

“<stdio.h>” on page 815 
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fptan — Calculate Tangent 

Format linclude <builtin.h> 

double _fptan(double x) ; 

Description Language Level: Extension 

_fptan calculates the tangent of x, where x is expressed in radians. The value of x 
must be less than 2**63. This function causes the compiler to emit the appropriate 
80387 instruction for the calculation of tangent. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fptan. 

• You cannot parenthesize a _fptan function call, because parentheses specify a 
call to the backing code for the function in the library. 

Return Value _fptan returns the tangent of x expressed in radians. 

This example calculates the tangent of pi/4. 

#include <bui1tin.h> 

#inc1ude <stdio.h> 

int main(void) 

{ 

double pi; 
pi = 3.1415926; 

printf("The tangent of %lf is %lf.\n", pi/4.0, _f ptan(pi/4.0)); 
return 0; 

/**************************************************************************** 

The output should be : 

The tangent of 0.785398 is 1.000000. 

****************************************************************************/ 

i 

• “atan - atan2 — Calculate Arctangent” on page 61 

• “_fpatan — Calculate Arctangent” on page 246 

• “tan — Calculate Tangent” on page 645 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<builtin.h>” on page 801 
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fputc — Write Character 

Format linclude <stdio.h> 

int fputc(int c, FILE *stream ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

fputc converts c to an unsigned char and then writes c to the output stream at the 
current position and advances the file position appropriately. If the stream is opened 
with one of the append modes, the character is appended to the end of the stream. 

fputc is identical to putc is always implemented as a function call; it is never 
replaced by a macro. 


Return Value fputc returns the character written. A return value of EOF indicates an error. 



This example writes the contents of buffer to a file called myfi 1 e.dat. 

Note: Because the output occurs as a side effect within the second expression of the 
for statement, the statement body is null. 


#include <stdio.h> 
#include <stdlib.h> 


#define NUM_ALPHA 26 

int main(void) 

{ 

FILE *stream; 
i nt i; 
int ch; 

/* Don't forget the NULL char at the end of the string! */ 

char buffer[NUM_ALPHA+l] = "abcdefghijklmnopqrstuvwxyz"; 

if ((stream = fopen("myfi1e.dat", "w")) != NULL) { 
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/* Put buffer into file */ 

for (i =0; (i < sizeof(buffer)) && ((ch = fputc(buffer[i], stream)) != 
EOF); ++i) 

fclose(stream); 
return 0; 

} 

el se 

perror("Error opening myfile.dat"); 
return EXIT_FAILURE; 

/**************************************************************************** 
The output data file myfile.dat should contain: 

abcdefghij klmnopqrstuvwxyz 

****************************************************************************/ 


• “fgetc — Read a Character” on page 225 

• “_fputchar — Write Character” on page 254 

• “putc - putchar — Write a Character” on page 468 

• “_putch — Write Character to Screen” on page 470 

• “<stdio.h>” on page 815 
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fputchar — Write Character 

Format linclude <stdio.h> 

int _fputchar(int c); 

Description Language Level: Extension 

_fputchar writes the single character c to the stdout stream at the current position. 
It is equivalent to the following fputc call: 

fputc(c, stdout); 

For portability, use the ANSI/ISO fputc function instead of _fputchar. 

Return Value _fputchar returns the character written. A return value of EOF indicates that a 
write error has occurred. Use terror and feof to tell whether this is an error 
condition or the end of the file. 

This example writes the contents of buffer to stdout: 
linclude <stdio.h> 

int main(void) 

{ 

char buffer[80]; 
int i ,ch = 1; 

for (i =0; i <80; i++) 
bufferfi] = 'c 1 ; 

for (i =0; (i < 80) && (ch != EOF); i++) 
ch = _fputchar(buffer[i]); 
printf ("\n"); 
return 0; 

/■*********************************************■***************'**'***'*'**'***'*'**'*'* 

The output should be similar to: 

ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc 

ici<ic-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-ki<‘k-k-k‘k-k-k‘k-k-ki(-k-k‘k-k-k‘k-k-k‘k-ki< , k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k^ 

} 

• “_fgetchar — Read Single Character from stdin” on page 227 

• “fputc — Write Character” on page 252 

• “putc - putchar — Write a Character” on page 468 

• “_putch — Write Character to Screen” on page 470 

• “<stdio.h>” on page 815 
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fputs — Write String 

Format linclude <stdio.h> 

int fputs(const char *string, FILE *stream); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fputs copies string to the output stream at the current position. It does not copy 
the null character (\0) at the end of the string. 

Return Value fputs returns EOF if an error occurs; otherwise, it returns a non-negative value. 

This example writes a string to a stream. 

#include <stdio.h> 

Idefine NUM_ALPHA 26 

int main(void) 

{ 

FILE *stream; 
int num; 

/* Do not forget that the '\0' char occupies one character */ 

static char buffer[NUM_ALPHA+1] = "abcdefghijklmnopqrstuvwxyz"; 

if ((stream = fopen("myfile.dat", "w")) != NULL) { 

/* Put buffer into file */ 

if ((num = fputs(buffer, stream)) != EOF) { 

/* Note that fputs() does not copy the \0 character */ 

printf("Total number of characters written to file = %i\n", num); 
fclose(stream); 

} 

else /* fputs failed */ 

perror("fputs failed"); 

} 

el se 

perror("Error opening myfile.dat"); 
return 0; 

/**************************************************************************** 

The output should be: 

Total number of characters written to file = 26 
****************************************************************************/ 

} 

• “_cputs — Write String to Screen” on page 114 

• “fgets — Read a String” on page 230 
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• “gets — Read a Line” on page 309 

• “puts — Write a String” on page 473 

• “<stdio.h>” on page 815 
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fputwc — Write Wide Character 

Format linclude <stdio.h> 

linclude <wchar.h> 

wint_t fputwc(wint_t wc, FILE *stream ); 

Description Language Level: ANSI 93, XPG4 

fputwc converts the wide character wc to a multibyte character and writes it to the 
output stream pointed to by stream at the current position. It also advances the file 
position indicator appropriately. If the file cannot support positioning requests, or if 
the stream was opened with append mode, the character is appended to the stream. 

The behavior of fputwc is affected by the LC_CTYPE category of the current locale. 

If you change the category between subsequent operations on the same stream, 
undefined results can occur. Using non-wide-character functions with fputwc on the 
same stream results in undefined behavior. 

After calling fputwc, flush the buffer or reposition the stream pointer before calling a 
read function for the stream. After reading from the stream, flush the buffer or 
reposition the stream pointer before calling fputwc, unless EOF has been reached. 

Return Value fputwc returns the wide character written. If a write error occurs, the error 

indicator for the stream is set and fputwc returns WEOF. If an encoding error occurs 
during conversion from wide character to a multibyte character, fputwc sets errno to 
EILSEQ and returns WEOF. 

This example opens a file and uses fputwc to write wide characters to the file. 

#inc1ude <stdio.h> 

#inc1ude <wchar.h> 

#inc1ude <errno.h> 

int main(void) 

1 

FILE *stream; 

wchar_t *wcs = L"A character string."; 
int i; 

if (NULL == (stream = fopen("fputwc.out", "w"))) { 
printf("Unable to open: \"fputwc.out\".\n"); 
exit(l); 

} 
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for (i = 0; wcs[i] != L'\0'; i++) { 
errno = 0; 

if (WEOF s= fputwc(wcs[i], stream)) { 

printf("Unable to fputwc() the wide character.\n" 

"wcs[%d] = Ox%lx\n", i, wcs[i]); 
if (EILSEQ == errno) 

printf("An invalid wide character was encountered.\n"); 
exit(l); 


fclose(stream); 
return 0; 

/it'k-kie-k-kle-k-k'k-k-k'k-klt'k-k-klc-k-kle-k-k'k-k-k'k-k-kle-k-kle-k-k'k-k-k-k-k-k'k-k-klc-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k 

The output file fputwc.out should contain : 

A character string. 

■k-k-k-k-k-k-k-k-k-kic-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-kick-k-k-k-kick-k-k-k-k^ 

} 



“fgetwc — Read Wide Character from Stream” on page 232 

“fputc — Write Character” on page 252 

“_fputchar — Write Character” on page 254 

“fputws — Write Wide-Character String” on page 259 

“_putch — Write Character to Screen” on page 470 

“<stdio.h>” on page 815 

“<wchar.h>” on page 821 
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fputws — Write Wide-Character String 

Format linclude <stdio.h> 

linclude <wchar.h> 

int fputws(const wchar_t *wcs, FILE *stream); 

Description Language Level: ANSI, SAA, XPG4 

fputws converts the wide-character string wcs to a multibyte-character string and 
writes it to stream as a multibyte character string. It does not write the terminating 
null byte. 

The behavior of fputws is affected by the LC_CTYPE category of the current locale. 
If you change the category between subsequent operations on the same stream, 
undefined results can occur. Using non-wide-character functions with fputws on the 
same stream results in undefined behavior. 


After calling fputws, flush the buffer or reposition the stream pointer before calling a 
read function for the stream. After a read operation, flush the buffer or reposition the 
stream pointer before calling fputws, unless EOF has been reached. 


Return Value fputws returns a non-negative value if successful. If a write error occurs, the error 
indicator for the stream is set and fputws returns -1. If an encoding error occurs in 
converting the wide characters to multibyte characters, fputws sets errno to EILSEQ 
and returns -1. 



This example opens a file and writes a wide-character string to the file using fgetws. 

#inc1ude <stdio.h> 

#include <wchar.h> 

#include <errno.h> 


int main(void) 

{ 

FILE *stream; 

wchar_t *wcs = L"This test string should not return -1"; 

if (NULL == (stream = fopen("fputws.out", "w 11 ))) { 
printf("Unable to open: V'fputws.out\".\n"); 
exit(l); 

} 


errno = 0; 

if (EOF == fputws(wcs, stream)) { 

printf("Unable to complete fputws() function.\n"); 
if (EILSEQ == errno) 

printf("An invalid wide character was encountered.\n"); 
exit(l); 

} 

fclose(stream); 
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return 0; 

/**************************************************************************** 

The output file fputws.out should contain : 

This test string should not return -1 

****************************************************************************/ 

} 

• “fgetws — Read Wide-Character String from Stream” on page 234 

• “fputs — Write String” on page 255 

• “fputwc — Write Wide Character” on page 257 

• “<stdio.h>” on page 815 

• “<wchar.h>” on page 821 
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fread — Read Items 


Format linclude <stdio.h> 

size_t fread(void *buffer, size_t size, size_t count, 
FILE *stream); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

fread reads up to count items of size length from the input stream and stores them 
in the given buffer. The position in the file increases by the number of bytes read. 


Return Value fread returns the number of full items successfully read, which can be less than 

count if an error occurs or if the end-of-file is met before reaching count. If size 
or count is 0 , fread returns zero and the contents of the array and the state of the 
stream remain unchanged. 


Use ferror and feof to distinguish between a read error and an end-of-file. 



This example attempts to read NUM_ALPHA characters from the file myfile.dat. If 
there are any errors with either fread or fopen, a message is printed. 

#include <stdio.h> 


#define NUM_ALPHA 26 

int main(void) 

{ 

FILE *stream; 

int num; /* number of characters read from stream */ 

/* Do not forget that the '\0' char occupies one character too! */ 

char buffer[NUM_ALPHA+l]; 

if ((stream = fopen("myfile.dat", "r")) != NULL) { 

num = fread(buffer, sizeof(char), NUM_ALPHA, stream); 

if (num) { /* fread success */ 

printf("Number of characters has been read = %i\n", num); 
buffer[num] = 1 \0'; 
printf("buffer = %s\n", buffer); 
fclose(stream); 

1 
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else { 

/* fread failed 

*/ 

if (ferror(stream)) 

/* possibility 1 

*/ 

perror("Error reading myfile.dat"); 



else 



if (feof(stream)) 

/* possibi1ity 2 

*/ 


perror("EOF found"); 


el se 

perror("Error opening myfile.dat"); 
return 0; 

/**************************************************************************** 

The output should be: 

Number of characters has been read = 26 
buffer = abcdefghijklmnopqrstuvwxyz 

****************************************************************************/ 

} 



“feof — Test End-of-File Indicator” on page 222 
“ferror — Test for Read/Write Errors” on page 223 
“fopen — Open Files” on page 243 
“fwri te — Write Items” on page 289 
“read — Read Into Buffer” on page 482 
“<stdio.h>” on page 815 
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free — Release Storage Blocks 

Format linclude <std1ib.h> /* also in <malloc.h> */ 

void free(void *ptr ); 


Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

free frees a block of storage, ptr points to a block previously reserved with a call 
to one of the memory allocation functions (such as cal 1 oc, _umal 1 oc, or 
_treal 1 oc). The number of bytes freed is the number of bytes specified when you 
reserved (or reallocated, in the case of realloc) the block of storage. If ptr is NULL, 
free simply returns. 

Note: Attempting to free a block of storage not allocated with a C memory 
management function or a block that was previously freed can affect the subsequent 
reserving of storage and lead to undefined results. 


Return Value There is no return value. 



This example uses calloc to allocate storage for x array elements and then calls free 
to free them. 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

long *array; /* start of the array */ 

long *index; /* index variable */ 

int i; /* index variable */ 

int num = 100; /* number of entries of the array */ 

printf("Al1ocating memory for %d long integers.\n", num); 

/* allocate num entries */ 

if ((index = array = calloc(num, sizeof(long))) != NULL) { 


/* . */ 

/* do something with the array */ 

/* . */ 


free(array); 

} 


/* deallocates array*/ 
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else { /* Out of storage */ 

perror("Error: out of storage"); 
abort(); 

} 

return 0; 

/•k-k-kle-k-k'k-k-kle-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-klck-k-k-k-k-k 

The output should be: 

Allocating memory for 100 long integers. 

} 



Managing Memory in the Programming Guide 
“_al loca — Temporarily Reserve Storage Block” on page 53 
“cal loc — Reserve and Initialize Storage” on page 80 
“_debug_free — Release Memory” on page 141 
“_debug_tfree — Release Tiled Memory” on page 151 
“mal loc — Reserve Storage Block” on page 403 
“real loc — Change Reserved Storage Block Size” on page 484 
“_tfree — Free Tiled Storage Block” on page 659 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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_freemod — 

Format 

Description 


Return Value 



Free User DLL 

linclude <std1ib.h> 

int _freemod(unsigned long module_handle); 

Language Level: Extension 

_freemod frees all references to a dynamic link library (DLL) for the calling process. 
It is the counterpart of the _1 oadmod function, which loads a DLL for the process. 

The module_handle is the module handle of the DLL, which was returned by 
_1 oadmod. 

Note: _1 oadmod and _freemod perform exactly the same function as the OS/2 APIs 
DosLoadModule and DosFreeModul e. They are provided for compatibility with 
earlier VisualAge C++ releases only, and will not be supported in future 
versions. Use DosLoadModule and DosFreeModule instead. Lor more details on 
these APIs, see the Control Program Guide and Reference. 

_freemod returns 0 if successful. If not, _freemod returns -1 and sets errno to 
EOS2ERR. 

This example loads the DLL mark with _1 oadmod, and uses the OS/2 function 
DosQueryProcAddr to get the address of the function dor from within the DLL. It then 
calls that function, which multiplies two integers passed to it. When the function and 
DLL are no longer needed, the program frees the DLL module. The macro INCL_D0S 
and the types PFN and APIRET are required for the OS/2 call, and are defined by 
including the <os2.h> header file. 

Note: To run this program, you must first create mark.dll. Copy the code for the 
PLUS function into a file called mark.c, and the code for the ,DEF file into 
mark.def. Eliminate the comments from these two files. Compile with the 
command: 

icc /Ge- mark.c mark.def 
You can then run the example. 
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#define INCL_D0S 
#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

/* This is the code for MARK.DEF 

LIBRARY MARK 

PROTMODE 

EXPORTS PLUS */ 

/* This is the code for PLUS function in the DLL 
#pragma linkage( PLUS, system ) 
int PLUS( int a , int b) 

{ 

return a + b; 

} */ 

int main(void) 

{ 

int x = 4,y = 7; 
unsigned long handle; 


char *modname = "MARK"; /* DLL name */ 
char *fname = "PLUS"; /* function name */ 
PFN faddr; /* pointer to function */ 
APIRET rc; /* return code from DosQueryProcAddr */ 

/* dynamically load the 'mark' DLL */ 


if (_loadmod(modname, &handle)) { 

printf("Error loading module %s\n", modname); 
return EXIT_FAILURE; 

} 


/* get function address from DLL */ 

rc = DosQueryProcAddr(handle, 0, fname, &faddr); 
if (0 == rc) { 

printf("Cal 1ing the function from the %s DLL to add %d and %d\n", modname, 
x, y); 

printf("The result of the function call is %d\n", faddr(x, y)); 

} 

else { 

printf("Error locating address of function %s\n", fname); 

_freemod(handle); 
return EXIT_FAILURE; 
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if (_freemod(handle)) { 

printf("Error in freeing the %s DLL module\n", modname); 
return EXIT_FAILURE; 

} 

printf("Reference to the %s DLL module has been freed\n", modname); 
return 0; 

/**************************************************************************** 
The output should be: 

Calling the function from the MARK DLL to add 4 and 7 
The result of the function call is 11 
Reference to the MARK DLL module has been freed 
****************************************************************************/ 


“Building Dynamic Link Libraries” in the Programming Guide 
“_1 oadmod — Load DLL” on page 376 
“<stdlib.h>” on page 816 
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freopen — Redirect Open Files 

Format linclude <stdio.h> 

FILE *freopen(const char *filename, const char *mode, FILE *stream ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

freopen closes the file currently associated with stream and reassigns stream to the 
file specified by fi lename. The freopen function opens the new file associated with 
stream with the given mode , which is a character string specifying the type of access 
requested for the file. You can also use the freopen function to redirect the standard 
stream files stdin, stdout, and stderr to files that you specify. 

If filename is an empty string, freopen closes and reopens the stream to the new 
open mode, rather than reassigning it to a new file or device. You can use freopen 
with no file name specified to change the mode of a standard stream from text to 
binary without redirecting the stream, for example: 

fp = freopen"rb", stdin); 

You can use the same method to change the mode from binary back to text. 

Portability Note: This method is included in the SAA C definition, but not in the 
ANSI/ISO C standard. 


See “fopen — Open Files” on page 243 for a description of the mode parameter. 


Return Value freopen returns a pointer to the newly opened stream. If an error occurs, freopen 
closes the original file and returns a NULL pointer value. 



This example closes the streaml data stream and reassigns its stream pointer. Note 
that streaml and stream2 will have the same value, but they will not necessarily have 
the same value as stream. 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

FILE *stream,*streaml,*stream2; 

stream = fopen("myfile.dat", "r"); 
streaml = stream; 

if (NULL == (stream2 = freopen("", "w+", streaml))) 
return EXIT_FAILURE; 
fcl ose(stream2); 
return 0; 

} 

• “close — Close File Associated with Handle” on page 99 
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• “fclose — Close Stream” on page 212 

• “_fcloseal 1 — Close All Open Streams” on page 213 

• “fopen — Open Files” on page 243 

• “open — Open File” on page 447 

• “_sopen — Open Shared File” on page 545 

• “<stdio.h>” on page 815 
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frexp — Separate Floating-Point Value 

Format linclude <math.h> 

double frexp(double x, int *expptr); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

frexp breaks down the floating-point value x into a term m for the mantissa and 
another term n for the exponent, such that x=m* 2 n , and the absolute value of m is 
greater than or equal to 0.5 and less than 1.0 or equal to 0. frexp stores the integer 
exponent n at the location to which expptr points. 


Return Value frexp returns the mantissa term m. If x is 0 , frexp returns 0 for both the mantissa 
and exponent. The mantissa has the same sign as the argument x. The result of the 
frexp function cannot have a range error. 



This example decomposes the floating-point value of x, 16.4, into its mantissa 0.5125, 
and its exponent 5. It stores the mantissa in y and the exponent in n. 

#include <math.h> 

int main(void) 

{ 

double x,m; 
int n; 


x = 16.4; 
m = frexp(x, &n); 

printf("The mantissa is %lf and the exponent is %d\n", m, n); 
return 0; 

/************'***'*'********'******************'*'********'*********'***'**'***'*'**'*'**'** 

The output should be: 

The mantissa is 0.512500 and the exponent is 5 

■k-k-k-klt-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-klc-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-klck-k-k-k-klck-k'k-k-k/ 

} 



“1 dexp — Multiply by a Power of Two” on page 372 
“modf — Separate Floating-Point Value” on page 440 
“<math.h>” on page 811 
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fscanf — Read Formatted Data 

Format linclude <stdio.h> 

int fscanf (FILE * stream , const char *format-string, argument-list); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

fscanf reads data from the current position of the specified stream into the locations 
given by the entries in argument-list, if any. Each entry in argument-list must 
be a pointer to a variable with a type that corresponds to a type specifier in 
format-string. 

The format-string controls the interpretation of the input fields and has the same 
form and function as the format-string argument for the scanf function. See 
“scanf — Read Data” on page 517 for a description of format-string. 

In extended mode, the fscanf function also reads in the strings "INFINITY", "INF", and 
"NAN" (in upper or lowercase) and converts them to the corresponding floating-point 
value. The sign of the value is determined by the format specification. See “Infinity 
and NaN Support” on page 33 for more information on infinity and NaN values. 

Return Value fscanf returns the number of fields that it successfully converted and assigned. The 
return value does not include fields that fscanf read but did not assign. 

The return value is EOF if an input failure occurs before any conversion, or the 
number of input items assigned if successful. 

This example opens the file myfile.dat for reading and then scans this file for a 
string, a long integer value, a character, and a floating-point value. 
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#include <stdio.h> 

#define MAX_LEN 80 

int main(void) 

{ 

FILE *stream; 

1ong 1; 
float fp; 

char s[MAX_LEN+l] ; 
char c; 

stream = fopen("myfile.dat", "r"); 

/* Put in various data. */ 

fscanf(stream, "%s", &s[0]); 
fscanf(stream, "%ld", &1); 
fscanf(stream, "%c", &c); 
fscanf(stream, "%f", &fp); 
printf("string = %s\n", s); 
printf("long double = %ld\n", 1); 
printf("char = %c\n", c); 
printf("float = %f\n", fp); 
return 0; 

/**************************************************************************** 

If myfile.dat contains: 
abcdefghijklmnopqrstuvwxyz 343.2. 

The output should be: 

string = abcdefghijklmnopqrstuvwxyz 
long double = 343 
char = . 

float = 2.000000 

****************************************************************************/ 



“Infinity and NaN Support” on page 33 

“_cscanf — Read Data from Keyboard” on page 127 

“fpri ntf — Write Formatted Data to a Stream” on page 249 

“scanf — Read Data” on page 517 

“sscanf — Read Data” on page 559 

“<stdio.h>” on page 815 
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fseek — Reposition File Position 

Format linclude <stdio.h> 

int fseek(FILE *stream, long int offset, int origin ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

fseek changes the current file position associated with stream to a new location 
within the file. The next operation on the stream takes place at the new location. 

On a stream open for update, the next operation can be either a reading or a writing 
operation. 

The origin must be one of the following constants defined in <stdio.h>: 

Origin Definition 

SEEK_SET Beginning of file 
SEEK_CUR Current position of file pointer 
SEEK_END End of file 

For a binary stream, you can also change the position beyond the end of the file. An 
attempt to position before the beginning of the file causes an error. If successful, 
fseek clears the end-of-file indicator, even when origin is SEEK_END, and undoes the 
effect of any preceding ungetc function on the same stream. 

Note: For streams opened in text mode, fseek has limited use because some system 
translations (such as those between carriage-return-line-feed and new line) can 
produce unexpected results. The only fseek operations that can be relied upon to 
work on streams opened in text mode are seeking with an offset of zero relative to 
any of the origin values or seeking from the beginning of the file with an offset value 
returned from a call to ftel 1. See the chapter “Performing I/O Operations” in the 
Programming Guide for more information. 

Return Value fseek returns 0 if it successfully moves the pointer. A nonzero return value 

indicates an error. On devices that cannot seek, such as terminals and printers, the 
return value is nonzero. 
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This example opens a file myfi 1 e.dat for reading. After performing input operations 
(not shown), fseek moves the file pointer to the beginning of the file. 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

FILE *stream; 
int result; 



stream = fopen("myfile.dat", "r"); 

result = fseek(stream, 0L, SEEK_SET); /* moves the pointer to the 

beginning of the file */ 

if (result) /* fail to move the pointer to the */ 

return EXIT_FAILURE; /* beginning of the file */ 

fclose(stream); 
return 0; 

• “fgetpos — Get File Position” on page 228 

• “fsetpos — Set File Position” on page 275 

• “f tel 1 — Get Current Position” on page 283 

• “rewi nd — Adjust Current File Position” on page 497 

• “ungetc — Push Character onto Input Stream” on page 721 

• “<stdio.h>” on page 815 
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fsetpos — Set File Position 

Format linclude <stdio.h> 

int fsetpos(FILE * stream , const fpos_t *pos); 

Description Language Level: ANSI, SAA, XPG4 

fsetpos moves any file position associated with stream to a new location within the 
file according to the value pointed to by pos. The value of pos was obtained by a 
previous call to the fgetpos library function. 

If successful, fsetpos clears the end-of-file indicator, and undoes the effect of any 
previous ungetc function on the same stream. 

After the fsetpos call, the next operation on a stream in update mode may be input or 
output. 


Return Value If fsetpos successfully changes the current position of the file, it returns 0. A 
nonzero return value indicates an error. 



This example opens a file myfile.dat for reading. After performing input operations 
(not shown), fsetpos moves the file pointer to the beginning of the file and rereads 
the first byte. 


#include <stdio.h> 


FILE *stream; 

int main(void) 

{ 

int retcode; 

fpos_t pos,post,pos2,pos3; 

char ptr[20]; /* existing file 'myfile.dat' has 20 byte records */ 

/* Open file, get position of file pointer, and read first record */ 

stream = fopen("myfile.dat", "rb"); 
fgetpos(stream, &pos); 
posl = pos; 

if (!fread(ptr, sizeof(ptr), 1, stream)) 
perror("fread error"); 
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/* Perform a number of read operations - the value of 1 pos 1 changes */ 

/* Re-set pointer to start of file and re-read first record */ 

fsetpos(stream, &posl); 
if (!fread(ptr, sizeof(ptr), 1, stream)) 
perror("fread error"); 
fcl ose(stream); 
return 0; 



“fgetpos — Get File Position” on page 228 
“fseek — Reposition File Position” on page 273 
“ftel 1 — Get Current Position” on page 283 
“rewi nd — Adjust Current File Position” on page 497 
“<stdio.h>” on page 815 
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fsin — Calculate Sine 

Format linclude <builtin.h> 

double _fsin( double x); 

Description Language Level: Extension 

_fsin calculates the sine of x, where x is expressed in radians. The value of x must 
be less than 2**63. This function causes the compiler to emit the appropriate 80387 
instruction for the calculation of sine. 


Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fsi n. 

• You cannot parenthesize a _fsin function call, because parentheses specify a call 
to the backing code for the function in the library. 

Return Value This function returns the sine of a variable x expressed in radians. 

This example calculates y as the sine of k/2. 

#include <bui1tin.h> 

#inc1ude <stdio.h> 

int main(void) 

{ 

double pi; 
pi = 3.1415926535; 

printf("The sine of %lf is %lf.\n", pi/2.0, _fsin(pi/2.0)); 
return 0; 

/**************************************************************************** 

The output should be : 

The sine of 1.570796 is 1.000000. 

****************************************************************************/ 

i 




“_fasin — Calculate Arcsine” on page 210 
“_fcossin — Calculate Cosine and Sine” on page 215 
“_fsi ncos — Calculate Sine and Cosine” on page 278 
“sin — Calculate Sine” on page 543 
“sinh — Calculate Hyperbolic Sine” on page 544 
“<builtin.h>” on page 801 
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fsincos — Calculate Sine and Cosine 

Format #include <builtin.h> 

double _fsincos(double x, double *y ); 


Description Language Level: Extension 

_fsincos calculates the sine of x, and stores the cosine in *y. This operation is 
faster than separately calculating the sine and cosine. Use _fsincos instead of 
_fcossi n when you will be using the sine first, and then the cosine. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _fsi ncos. 

• You cannot parenthesize a _fsincos function call because parentheses specify a 
call to the backing code for the function. 


Return Value This function returns the sine of x. 



This example calculates the sine of x and stores it in z, and stores the cosine of x in 

y. 

#include <bui1tin.h> 

#include <stdio.h> 


int main(void) 

{ 

double x, y, z; 

printf("Enter x:\n"); 
scanf("%lf", &x); 

z = _fsincos(x, &y); 

printf("The sine of %lf is %lf.\n", x, z); 
printf("The cosine of %lf is %lf.\n", x, y); 
return 0; 

/**************************************************************************** 
Assuming you enter : 1.0 

The output should be : 

The sine of 1.000000 is 0.841471. 

The cosine of 1.000000 is 0.540302. 

****************************************************************************/ 



“acos — Calculate Arccosine” on page 51 

“asin — Calculate Arcsine” on page 57 

“cos — Calculate Cosine” on page 111 

“cosh — Calculate Hyperbolic Cosine” on page 112 

“_facos — Calculate Arccosine” on page 208 
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• “_fasin — Calculate Arcsine” on page 210 

• “_fcos — Calculate Cosine” on page 214 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsi n — Calculate Sine” on page 277 

• “sin — Calculate Sine” on page 543 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “<builtin.h>” on page 801 
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fsqrt — Calculate Square Root 

Format linclude <builtin.h> 

double _fsqrt(double x ); 

Description Language Level: Extension 

_fsqrt computes the square root of x using the FSQRT 80387 instruction. Note that 
this function does not set errno as the sqrt function does. If you pass a negative 
value to this function, an exception is generated. 

Note: _fsqrt is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _fsqrt. 

• You cannot parenthesize a call to _fsqrt. (Parentheses specify a call to the 
function's backing code, and _fsqrt has none.) 

Return Value _fsqrt returns the value of the square root of x. 

This example calculates the square root of 4. 

#include <bui1tin.h> 
linclude <stdio.h> 

int main(void) 

{ 

double x; 
x = 4.0; 

printf("The square root of %lf is %lf.\n", x, _fsqrt(x)); 
return 0; 

^•k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-kick-k-k'k 

The output should be : 

The square root of 4.000000 is 2.000000. 

} 

• “sqrt — Calculate Square Root” on page 556 

• “<math.h>” on page 811 
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fstat — Information about Open File 

Format finclude <sys\stat.h> 

finclude <sys\types.h> 

int fstat(int handle, struct stat *buffer); 


Description Language Level: XPG4, Extension 


fstat obtains information about the open file associated with the given handle and 
stores it in the structure to which buffer points. The <sys\stat.h> include file 
defines the stat structure. The stat structure contains the following fields: 

Field Value 

st_mode Bit mask for file mode information, fstat sets the S_IFCHR bit if 
handle refers to a device. The S_IFD1R bit is set if pathname 
specifies a directory. It sets the S_IFREG bit if handle refers to an 
ordinary file. It sets user read/write bits according to the permission 
mode of the file. The other bits have undefined values. 


SJFREG 
(regular file) 
SJFDIR 
S IFCHR 


FEDCBA987654321 0 



st_dev 

st_rdev 

st_nlink 

st_size 

st_atime 

st_mtime 

st_ctime 


Drive number of the disk containing the file. 

Drive number of the disk containing the file (same as st_dev). 
Always 1. 

Size of the file in bytes. 

Time of last access of file. 

Time of last modification of file. 

Time of file creation. 


There are three additional fields in the stat structure for portability to other operating 
systems; they have no meaning under the OS/2 operating system. 
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Notes: 

1. If the given handle refers to a device, the size and time fields in the stat 
structure are not meaningful. 

2. In earlier releases of C Set ++, fstat began with an underscore (_fstat). 
Because it is defined by the X/Open standard, the underscore has been removed. 
For compatibility, VisualAge C++ will map _fstat to fstat for you. 


Return Value If it obtains the file status information, fstat returns 0. A return value of -1 

indicates an error, and fstat sets errno to EBADF, showing an incorrect file handle. 

This example uses fstat to report the size of a file named data. 

linclude <time.h> 
linclude <sys\types.h> 
linclude <sys\stat.h> 
linclude <stdio.h> 

int main(void) 

{ 

struct stat but; 

FILE *fp; 
int fh,result; 

char *buffer = "A line to output"; 

fp = fopen("data", "w+"); 
fprintf(fp, "%s", buffer); 
fflush(fp); 
fclose(fp); 

fp = fopen("data", "r"); 
if (0 s= fstat(fileno(fp), &buf)) { 

printf("file size is %ld\n", buf.st_size); 
printf("time modified is %s\n", ctime(&buf.st_atime)); 

} 

else 

printf("Bad file handle\n"); 
fclose(fp); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

file size is 16 

time modified is Thu May 16 16:08:14 1995 

****************************************************************************/ 




“stat — Get Information about File or Directory” on page 561 
“<sys\stat.h>” on page 819 
“<sys\types.h>” on page 819 
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ftel 1 — Get Current Position 

Format linclude <stdio.h> 

long int ftell(FILE *stream); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

ftel 1 finds the current position of the file associated with stream. For a fixed-length 
binary file, the value returned by ftel 1 is an offset relative to the beginning of the 
stream. 

Note: For buffered text streams, ftel 1 returns an incorrect file position if the file 
contains new-line characters instead of carriage-return line-feed combinations. Your 
file would only contain new-line characters if you previously used it as a binary 
stream. To avoid this problem, either continue to process the file as a binary stream, 
or use unbuffered I/O operations. 


Return Value ftell returns the current file position. On error, ftell returns -1L and sets errno to 
a nonzero value. 



This example opens the file myfile.dat for reading. It reads enough characters to fill 
half of the buffer and prints out the position in the stream and the buffer. 

#inc1ude <stdio.h> 


#define NUM_ALPHA 26 

Idefine NUM CHAR 6 


int main(void) 

{ 

FILE *stream; 
i nt i; 
char ch; 

char buffer[NUM_ALPHA]; 
long position; 
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if ((stream = fopen("myfi1e.dat", "r")) != NULL) { 

/* read into buffer */ 

for (i =0; (i < NUM_ALPHA/2) && ((buffer[i] = fgetc(stream)) != EOF); 

++i) 

if (i s= NUM_CHAR-1) { /* We want to be able to position the 
file pointer to the character in 
position NUM_CHAR */ 

position = ftel1(stream); 

printf("Current position of the file is stored.\n"); 

} 

bufferfi] = '\0'; 

fseek(stream, position, SEEK_SET); 

ch = fgetc(stream); /* get the character at position NUM_CHAR */ 

fclose(stream); 

} 

else 

perror("Error opening myfile.dat"); 
return 0; 



“fseek — Reposition File Position” on page 273 
“fgetpos — Get File Position” on page 228 
“fopen — Open Files” on page 243 
“fsetpos — Set File Position” on page 275 
“<stdio.h>” on page 815 
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ftime — Store Current Time 


Format 


Description 


Return Value 



linclude <sys\timeb.h> 
linclude <sys\types.h> 
void _ftime(struct timeb *timeptr ); 


Language Level: Extension 


_ftime gets the current time and stores it in the structure to which timeptr points. 
The <sys\timeb.h> include file contains the definition of the timeb 

structure. It contains four fields: 


time 

millitm 

timezone 


dstflag 


The time in seconds since 00:00:00 Coordinated Universal Time, January 
1, 1970. 

The fraction of a second, in milliseconds. 

The difference in minutes between Coordinated Universal Time and local 
time, going from east to west. _ftime sets the value of timezone from 
the value of the global variable _timezone. 

Nonzero if daylight saving time is currently in effect for the local time 
zone. For an explanation of how daylight saving time is determined, see 
“tzset — Assign Values to Locale Information” on page 681. 


There is no return value. 

This example polls the system clock, converts the current time to a character string, 
prints the string, and saves the time data in the structure timebuffer. 

#include <sys\types.h> 

#include <sys\timeb.h> 

#include <stdio.h> 

#include <time.h> 

int main(void) 

{ 

struct timeb timebuffer; 

_ftime(&timebuffer); 

printf("the time is %s\n", ctime(&(timebuffer.time))); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

the time is Thu May 16 16:08:17 1995 

****************************************************************************/ 

i 


• “asctime — Convert Time to Character String” on page 55 

• “ctime — Convert Time to Character String” on page 129 

• “gmtime — Convert Time” on page 321 
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• “1 ocal time — Convert Time” on page 385 

• “mktime — Convert Local Time” on page 438 

• “t i me — Determine Current Time” on page 666 

• “tzset — Assign Values to Locale Information” on page 681 

• “<sys\timeb.h>” on page 819 

• “<sys\types.h>” on page 819 


286 VisualAge C++ C Library Reference 




fullpath 


full path — Get Full Path Name of Partial Path 

Format linclude <std1ib.h> 

char *_ful1 path(char *pathbuf, char *partialpath, size_t n ); 

Description Language Level: Extension 

_ful 1 path gets the full path name of the given partial path name partialpath. and 

stores it in pathbuf. The integer argument n specifies the maximum length for the 
path name. An error occurs if the length of the path name, including the terminating 
null character, exceeds n characters. 

If pathbuf is NULL. _f ul 1 path uses malloc to allocate a buffer of size _MAX_PATH 
bytes to store the path name. 


Return Value _f ul 1 path returns a pointer to pathbuf. If an error occurs, _ful 1 path returns 
NULL and sets errno to one of the following values: 



Value Meaning 

ENOMEM Unable to allocate storage for the buffer. 

ERANGE The path name is longer than n characters. 

EOS2ERR A system error occurred. Check _doserrno for the specific OS/2 

error code. 

This example uses _f u 11 path to get and store the full path name of the current 
directory. 

#include <stdio.h> 

#include <stdlib.h> 

#include <errno.h> 


int main(void) 

{ 

char *retBuffer; 


retBuffer = _ful1path(NULL, 0); 
if (NULL == retBuffer) { 

printf("An error has occurred, errno is set to %d.\n", errno); 

} 

el se 

printf("Ful1 path name of current directory is %s.\n", retBuffer); 
return 0; 


/**************************************************************************** 
The output should be similar to: 

Full path name of current directory is D:\BIN. 
****************************************************************************/ 

} 



“_getcwd — Get Path Name of Current Directory” on page 300 
“_getdcwd — Get Full Path Name of Current Directory” on page 302 
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• “_makepath — Create Path” on page 401 

• “mal loc — Reserve Storage Block” on page 403 

• “_spl i tpath — Decompose Path Name” on page 552 

• “<stdlib.h>” on page 816 
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fwrite — Write Items 

Format linclude <stdio.h> 

size_t fwrite(const void * buffer, size_t size, size_t count, 

FILE *stream); 

Description Language Level: ANSI, SAA SAA, POSIX, XPG4 

fwrite writes up to count items, each of size bytes in length, from buffer to the 
output stream. 

Return Value fwrite returns the number of full items successfully written, which can be fewer 
than count if an error occurs. 

This example writes NUM 1 ong integers to a stream in binary format. 

#include <stdio.h> 

Idefine NUM 100 

int main(void) 

{ 

FILE *stream; 
long 1 ist[NUM] ; 
int numwritten; 

stream = fopenC'myfile.dat", "w+b"); 

/* assign values to list[] */ 

numwritten = fwrite(list, sizeof(long), NUM, stream); 
printf("Number of items successfully written : %d\n", numwritten); 
return 0; 

/**************************************************************************** 

The output should be: 

Number of items successfully written : 100 
****************************************************************************/ 
i 

• “fopen — Open Files” on page 243 

• “fread — Read Items” on page 261 

• “read — Read Into Buffer” on page 482 

• “wri te — Writes from Buffer to File” on page 799 

• “<stdio.h>” on page 815 
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_fyl2x — Calculate y * log2(x) 

Format linclude <builtin.h> 

double _fyl 2x(double x, double y) ; 

Description Language Level: Extension 

_fyl2x computes the base-2 logarithm of x and multiplies it by y (y * log2(x)). 

The variable x cannot be negative. This instruction is designed with built-in 
multiplication to optimize the calculation of logarithms with arbitrary positive base: 
log b (x) = (log2(h)**-l) * log2(x) 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of_fy 12x. 

• You cannot parenthesize a _fyl2x function call, because parentheses specify a 
call to the backing code for the function in the library. 

Return Value _fyl2x returns the result of the formula y * log2(x). 

This example calculates (y * log2(x)), after prompting the user for values of x and y. 

#include <bui1tin.h> 
linclude <stdio.h> 

int main(void) 

{ 

double x, y; 

printf("Enter a value for x:\n"); 
scanf("%lf", &x); 
printf("Enter a value for y:\n"); 
scanf("%lf", &y); 

pri ntf ("%1 f * log2(%lf) is %lf.\n", y, x, _fyl2x(x, y)); 
return 0; 

/**************************************************************************** 

Assuming you enter 4.0 for x and 3.0 for y. 

The output should be : 

3.000000 * log2(4.000000) is 6.000000. 

****************************************************************************/ 

} 

• “_fyl2xpl — Calculate y * log2(x + 1)” on page 291 

• “_f2xml — Calculate (2**x) - 1” on page 292 

• “<builtin.h>” on page 801 
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_fyl2xpl — 

Format 

Description 


Return Value 



Calculate y * log2(x + 1) 

linclude <builtin.h> 

double _fyl2xpl(double x, double y) ; 

Language Level: Extension 

_fyl2xpl computes the base-2 logarithm of x+1 and multiplies it by y (y * 
log2(x+l)). The variable x must be in the range -(l-(sqrt(2)/2)) to (sqrt(2) - 1). 
_fyl2xpl provides improved accuracy over _fyl2x when logarithms of numbers very 
close to 1 are computed. When x is small, you can retain more significant digits by 
providing x to the _fyl2xpl function than by providing x+1 as an argument to the 
_fyl 2x function. 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of_fyl 2xpl. 

• You cannot parenthesize a _fy!2xpl function call, because parentheses specify a 
call to the backing code for the function in the library. 

_fyl2xpl returns the result of the formula y * log2(x+l). 

This example calculates (y * log2(x + 1)), after prompting the user for values of x 
and y. 

#include <builtin.h> 

#include <stdio.h> 

int main(void) 

{ 

double x, y; 

printf("Enter a value for x:\n"); 
scanf("%lf", &x); 
printf("Enter a value for y:\n"); 
scanf("%lf", &y); 

printf("%1f * 1og2(%lf + 1) is %lf.\n", y, x, _fyl2xpl(x, y)); 
return 0; 

/**************************************************************************** 

Assuming you enter 0.001 for x and 2.0 for y. 

The output should be : 

2.000000 * log2(0.001000 + 1) is 0.002884. 
****************************************************************************/ 

} 

• “_fyl2x — Calculate y * log2(x)” on page 290 

• “_f2xml — Calculate (2**x) - 1” on page 292 

• “<builtin.h>” on page 801 
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_f2xml — Calculate (2**x) - 1 

Format linclude <builtin.h> 

double _f2xml(double x); 

Description Language Level: Extension 

_f2xml calculates 2 raised to the power of x, minus 1 ((2**x)-l). The variable x 
must be in the range -1 to 1. This instruction is designed to produce very accurate 
results when x is close to 0. Large errors may occur for operands with magnitudes 
close to 1. You can exponentiate values other than 2 by using the formula x**y = 

2**(y * log2(x)). 

Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of _f2xml. 

• You cannot parenthesize a _f2xml function call, because parentheses specify a 
call to the backing code for the function in the library. 

Return Value This function returns the value of the formula (2**x)-l. 

This example calculates (2**x)-l after prompting the user for a value for x. 

#include <bui1tin.h> 
linclude <stdio.h> 

int main(void) 

{ 

double x; 

printf("Enter a value for x:\n"); 
scanf("%lf", &x); 

printf("(2**(%1f)) - 1 is %lf.\n", x, _f2xml(x)); 
return 0; 

/**************************************************************************** 
Assuming you enter : 0.001 

The output should be : 

(2**(0.001000)) - 1 is 0.000693. 

****************************************************************************/ 

} 

• “_fyl2x — Calculate y * log2(x)” on page 290 

• “_fyl2xpl — Calculate y * log2(x + 1)” on page 291 

• “<builtin.h>” on page 801 
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gamma — Gamma Function 

Format linclude <math.h> /* SAA extension to ANSI */ 

double gamma(double x); 

Description Language Level: SAA 

gamma computes the natural logarithm of the absolute value of G(x) (1 n(| G(x) |)), 
where 



Portability Note: According to the SAA standard, x must be a positive real value. 
Under the VisualAge C++ compiler, x can also be a negative integer. 

Return Value gamma returns the value of 1 n (| G (x) |) . If x is a negative value, errno is set to EDOM. 

If the result causes an overflow, gamma returns HUGE_VAL and sets errno to ERANGE. 

This example uses gamma to calculate 1 n(|G(x) |), where x = 42. 

#inc1ude <math.h> 

#include <stdio.h> 

int main(void) 

{ 

double x = 42,g_at_x; 

g_at_x = exp(gamma(x)); /* g_at_x = 3.345253e+49 */ 

printf("The value of G(%4.2f) is %7.2e\n", x, g_at_x); 
return 0; 

/**************************************************************************** 

The output should be: 

The value of G(42.00) is 3.35e+49 

****************************************************************************/ 

} 

• “Bessel Functions — Solve Differential Equations” on page 74 

• “erf - erfc — Calculate Error Functions” on page 199 

• “<math.h>” on page 811 
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gcvt — Convert Floating-Point to String 

Format linclude <stdlib.h> 

char *_gcvt(double value, int ndec, char *buffer); 

Description Language Level: Extension 

_gcvt converts a floating-point value to a character string pointed to by buffer. 

The buffer should be large enough to hold the converted value and a null character 
(\0) that _gcvt automatically adds to the end of the string. There is no provision for 
overflow. 

_gcvt tries to produce ndec significant digits in FORTRAN F format. Failing that, it 
produces ndec significant digits in FORTRAN E format. Trailing zeros might be 
suppressed in the conversion if they are significant. 

A FORTRAN F number has the following format: 


_Jr ri n n n + _1_ _X_1_ 



' U LULL . ' ^ ^ 

UfigifJ 


A FORTRAN E number has the following format: 



_gcvt also converts NaN and infinity values to the strings NAN and INFINITY, 
respectively. For more information on NaN and infinity values, see “Infinity and 
NaN Support” on page 33. 

Warning: For each thread, _ecvt, _fcvt and _gcvt use a single, dynamically 
allocated buffer for the conversion. Any subsequent call that the same thread makes 
to these functions destroys the result of the previous call. 
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Return Value _gcvt returns a pointer to the string of digits. If it cannot allocate memory to 

perform the conversion, _gcvt returns an empty string and sets errno to ENOMEM. 



This example converts the value -3.1415e3 to a character string and places it in the 
character array bufferl. It then converts the macro value _INF to a character string 
and places it in buffer2. 

#inc1ude <stdio.h> 

#include <stdlib.h> 

linclude <float.h> /* for the definition of _INF */ 


int main(void) 

{ 

char bufferl[10],buffer2 [10]; 

_gcvt(-3.1415e3, 7, bufferl); 

printf("The first result is %s \n", bufferl); 

_gcvt(_INF, 5, buffer2); 

printf("The second result is %s \n", buffer2); 
return 0; 

/**************************************************************************** 
The output should be: 

The first result is -3141.5 
The second result is INFINITY 

****************************************************************************/ 



“_ecvt — Convert Floating-Point to Character” on page 192 
“_fcvt — Convert Floating-Point to String” on page 217 
“Infinity and NaN Support” on page 33 
“<stdlib.h>” on page 816 
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getc - getchar — Read a Character 

Format linclude <stdio.h> 

int getc(FILE *stream ); 
int getchar(void); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

getc reads a single character from the current stream position and advances the 
stream position to the next character, getchar is identical to getc(stdin). 

getc is equivalent to fgetc except that, if it is implemented as a macro, getc can 
evaluate stream more than once. Therfore, the stream argument to getc should not 
be an expression with side effects. 

Return Value getc and getchar return the character read. A return value of EOF indicates an error 
or end-of-file condition. Use terror or feof to determine whether an error or an 
end-of-file condition occurred. 

This example gets a line of input from the stdin stream. You can also use 
getc(stdin) instead of getchar() in the for statement to get a line of input from 

stdin. 

linclude <stdio.h> 

Idefine LINE 80 

int main(void) 

{ 

char buffer[LINE+l]; 
i nt i; 
int ch; 

printf("Please enter string\n"); 

/* Keep reading until either: 

1. the length of LINE is exceeded or 

2. the input character is EOF or 

3. the input character is a newline character 

*/ 
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for (i =0; (i < LINE) && ((ch = getcharQ) ! = EOF) && (ch != '\n'); ++i) 
buffer[i] = ch; 

buffer[i] = '\0'; /* a string should always end with 1 \0 1 ! */ 

printf("The string is %s\n", buffer); 
return 0; 

/**************************************************************************** 
The output should be similar to: 

Please enter string 
hello world 

The string is hello world 

****************************************************************************/ 


• “fgetc — Read a Character” on page 225 

• “_fgetchar — Read Single Character from stdin” on page 227 

• “_getch - _getche — Read Character from Keyboard” on page 298 

• “putc - putchar — Write a Character” on page 468 

• “ungetc — Push Character onto Input Stream” on page 721 

• “gets — Read a Line” on page 309 

• “<stdio.h>” on page 815 
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getch - getche — Read Character from Keyboard 

Format linclude <conio.h> 

int _getch(void); 
int _getche(void); 

Description Language Level: Extension 

_getch reads a single character from the keyboard, without echoing. _getche reads 
a single character from the keyboard and displays the character read. Neither 
function can be used to read Ctrl-Break. 

You can use _kbhit to test if a keystroke is waiting in the buffer. If you call _getch 
or _getche without first calling _kbhit, the program waits for a key to be pressed. 

Return Value _getch and _getche return the character read. To read a function key or 

cursor-moving key, you must call _getch and _getche twice; the first call returns 0 
or E0H, and the second call returns the particular extended key code. 

This example gets characters from the keyboard until it finds the character 1 x 1 . 

linclude <conio.h> 
linclude <stdio.h> 

int main(void) 

{ 

int ch; 

printf("Type in some letters.\n"); 
printf("If you type in an 'x 1 , the program ends.\n"); 
for (; ; ) { 
ch - _getch(); 
if ( 1 x 1 == ch) { 

_ungetch(ch); 
break; 

} 

_putch(ch); 

} 

ch = _getch(); 

printf("\nThe last character was '%c'.", ch); 
return 0; 
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/**************************************************************************** 
Here is the output from a sample run: 

Type in some letters. 

If you type in an 'x', the program ends. 

One Two Three Four Five Si 
The last character was 'x'. 

****************************************************************************/ 


• “_cgets — Read String of Characters from Keyboard” on page 85 

• “fgetc — Read a Character” on page 225 

• “getc - getchar — Read a Character” on page 296 

• “_kbhit — Test for Keystroke” on page 369 

• “_putch — Write Character to Screen” on page 470 

• “_ungetch — Push Character Back to Keyboard” on page 723 

• “<conio.h>” on page 802 
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getcwd — Get Path Name of Current Directory 

Format linclude <direct.h> 

char *_getcwd(char *pathbuf, int r ); 

Description Language Level: Extension 

_getcwd gets the full path name of the current working directory and stores it in the 
buffer pointed to by pathbuf. The integer argument n specifies the maximum length 
for the path name. An error occurs if the length of the path name, including the 
terminating null character, exceeds n characters. 

If the pathbuf argument is NULL, _getcwd uses malloc to reserve a buffer of at least 
n bytes to store the path name. If the current working directory string is more than n 
bytes, a large enough buffer will be allocated to contain the string. You can later free 
this buffer using the _getcwd return value as the argument to free. 

Return Value _getcwd returns pathbuf. If an error occurs, _getcwd returns NULL and sets errno 
to one of the following values: 

Value Meaning 

ENOMEM Not enough storage space available to reserve n bytes (when pathbuf 

is NULL). 

ERANGE The path name is longer than n characters. 

EOS2ERR An OS/2 call failed. Use _doserrno to obtain more information about 

the return code. 

This example stores the name of the current working directory (up to _MAX_PATH 
characters) in a buffer. The value of _MAX_PATH is defined in <stdlib.h>. 

#include <direct.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

char buffer[_MAX_PATH]; 

if (NULL == getcwd(buffer, _MAX_PATH)) 
perror("getcwd error"); 

printf("The current directory is %s.\n", buffer); 
return 0; 

/•k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k 

The output should be similar to: 

The current directory is E:\C_0S2\MIG_XMPS 

icic-k-k'k-k-k'k-k-kle-k-k'k-k-k'k-k-kle-k-k-k-k-kle-k-kle-k-kle-k-k'k-k-kle-kit'k-k-kle-k-kic-kic-k-k-kle-k-k'k-k-kle-k-kle-k-k-k-k-k'k-kic'k-k-k'k-k'k/ 

} 
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• “chdi r — Change Current Working Directory” on page 87 

• “_ful 1 path — Get Full Path Name of Partial Path” on page 287 

• “_getdcwd — Get Full Path Name of Current Directory” on page 302 

• “_getdrive — Get Current Working Drive” on page 304 

• “mal loc — Reserve Storage Block” on page 403 

• “<direct.h>” on page 803 
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_getdcwd — 

Format 

Description 


Return Value 


Get Full Path Name of Current Directory 

linclude <direct.h> 

char *_getdcwd(int drive, char *pathbuf, int n ); 

Language Level: Extension 

_getdcwd gets the full path name for the current directory of the specified drive , and 
stores it in the location pointed to by pathbuf. The drive argument is an integer 
value representing the drive (A: is 1, B: is 2, and so on). 

The integer argument n specifies the maximum length for the path name. An error 
occurs if the length of the path name, including the terminating null character, 
exceeds n characters. 

If the pathbuf argument is NULL, _getdcwd uses malloc to reserve a buffer of at least 
n bytes to store the path name. If the current working directory string is more than n 
bytes, a large enough buffer will be allocated to contain the string. You can later free 
this buffer using the _getdcwd return value as the argument to free. 

Alternatives to this function are the DosQueryCurrentDir and DosQueryCurrentDisk 
API calls. 


_getdcwd returns pathbuf. If an error occurs, _getdcwd returns NULL and sets 
errno to one of the following values: 


Value 

ENOMEM 

ERANGE 

EOS2ERR 


Meaning 

Not enough storage space available to reserve n bytes (when 
pathbuf is NULL). 

The path name is longer than n characters. 

An OS/2 call failed. Use _doserrno to obtain more information 
about the return code. 
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This example uses _getdcwd to obtain the current working directory of drive C. 

#include <stdio.h> 

#include <direct.h> 
lire! ude <errno.h> 

int main(void) 

{ 

char *retBuffer; 

retBuffer = _getdcwd(3, NULL, 0); 
if (NULL == retBuffer) 

printf("An error has occurred, errno is set to %d.\n", errno); 
el se 

printf("%s is the current working directory in drive C.\n", retBuffer); 
return 0; 

/**************************************************************************** 
The output should be similar to: 

C:\ is the current working directory in drive C. 
****************************************************************************/ 

} 


• “chdi r — Change Current Working Directory” on page 87 

• “_chdrive — Change Current Working Drive” on page 89 

• “_ful 1 path — Get Full Path Name of Partial Path” on page 287 

• “_getcwd — Get Path Name of Current Directory” on page 300 

• “_getdrive — Get Current Working Drive” on page 304 

• “mal loc — Reserve Storage Block” on page 403 

• “<direct.h>” on page 803 
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_getdrive - 

Format 

Description 

Return Value 



Get Current Working Drive 

#include <direct.h> 
int _getdrive(void); 

Language Level: Extension 

_getdri ve gets the drive number for the current working drive. 

An alternative to this function is the DosQueryCurrentDisk API call. 

_getdrive returns an integer corresponding to alphabetical position of the letter 
representing the current working drive. For example. A: is 1, B: is 2, J: is 10, and so 
on. 

This example gets and prints the current working drive number. 

#include <stdio.h> 

#include <direct.h> 

int main(void) 

{ 

printf("Current working drive is %d.\n", _getdrive()); 
return 0; 

^•k , ki<‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k-k-k-k‘k-k-k-k-k-ki(-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k 

The output should be similar to: 

Current working drive is 5. 

} 

• “chdi r — Change Current Working Directory” on page 87 

• “_chdri ve — Change Current Working Drive” on page 89 

• “_getcwd — Get Path Name of Current Directory” on page 300 

• “_getdcwd — Get Full Path Name of Current Directory” on page 302 

• “<direct.h>” on page 803 
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getenv — Search for Environment Variables 

Format linclude <stdlib.h> 

char *getenv(const char *varname ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

getenv searches the list of environment variables for an entry corresponding to 
varname. 

Return Value getenv returns a pointer to the environment table entry containing the current string 
value of varname. The return value is NULL if the given variable is not currently 
defined or if the system does not support environment variables. 

You should copy the string that is returned because it may be written over by a 
subsequent call to getenv. 

In this example, pathvar points to the value of the PATH environment variable. 

#inc1ude <stdlib.h> 

int main(void) 

{ 

char *pathvar; 

pathvar = getenv("PATH"); 
if (NULL == pathvar) 

printf("Environment variable PATH is not defined.\n"); 
el se 

printf("Path set by environment variable PATH is successfully stored.\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

Path set by environment variable PATH is successfully stored. 
****************************************************************************/ 
i 

• “putenv — Modify Environment Variables” on page 471 

• “<stdlib.h>” on page 816 
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getmccoll — Get Next Collating Element from String 

Format linclude <collate.h> 

collel_t getmccol1(char **src) 

Description Language Level: Extension 

getmccol 1 finds the first sequence of characters in the array pointed to by src that 
constitute a valid multicharacter collating element. It then produces the col 1 el _t 
value that corresponds to that collating element. It also changes src to point to the 
next byte following that collating element. 

Return Value getmccol 1 returns the col lei_t value that represents the collating element found. 

If the object pointed to by src is a null pointer or points to a null character, 
getmccol 1 returns 0. 

This example uses getmccoll to find the first collating element in the string "de xyz" 
in the France locale. 

linclude <stdio.h> 
linclude <locale.h> 
linclude <col1ate.h> 

int main(void) 

{ 

char s[] = "de xyz"; 

char *str = s; 

coll el_t x; 

if (NULL == setlocale(LC_ALL, LC_C_FRANCE)) { 

printf("Setlocale(LC_ALL, LC_A_FRANCE) failed.\n"); 
exit(l); 

} 

x = getmccol1(&str); 
printf("getmccol1(\"%s\")\n", s); 
printf(" returns: \"%s\"\n", col 1tostr(x)); 
printf(" remainder of string: \"%s\"\n", str); 
return 0; 

/**************************************************************■*'**'*'*****'*'**'*'* 

The output should be similar to : 

getmccol1("de xyz") 
returns: "de " 
remainder of string: "xyz" 

■k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-kit'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k'k'k'k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-kick-kit/ 

) 

• “ccl ass — Return Characters in Character Class” on page 82 

• “col 1 equi v — Return List of Equivalent Collating Elements” on page 101 

• “col 1 order — Return List of Collating Elements” on page 103 

• “col 1 range — Calculate Range of Collating Elements” on page 105 
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• “col 1 tostr — Return String for Collating Element” on page 107 

• “getwmccol 1 — Get Next Collating Element from Wide String” on page 319 

• “i smccol 1 el — Identify Multi-Character Collating Element” on page 358 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “strtocol 1 — Return Collating Element for String” on page 619 

• “<collate.h>” on page 802 
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get pi d — Get Process Identifier 

Format linclude <process.h> 

int getpid(void); 

Description Language Level: XPG4, Extension 

getpid gets the process identifier that uniquely identifies the calling process. 

Note: In earlier releases of C Set ++, getpid began with an underscore (_getpid). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _getpid to getpid for you. 

Return Value getpid function the process identifier as an integer value. There is no error return 
value. 

This example prints the process identifier: 

linclude <process.h> 
linclude <string.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

printf("Process identifier is %05d\n", getpid()); 
return 0; 

/leit-k'k-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-kic-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k'k-k-k-k-k'k 

The output should be similar to: 

Process identifier is 00242 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-ki<‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k^ 

} 

• “_cwait — Wait for Child Process” on page 131 

• “execl - _execvpe — Load and Run Child Process” on page 200 

• “_spawnl - _spawnvpe — Start and Run Child Processes” on page 548 

• “<process.h>” on page 812 
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gets — Read a Line 

Format linclude <stdio.h> 

char *gets(char *buffer); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

gets reads a line from the standard input stream stdin and stores it in buffer. The 
line consists of all characters up to and including the first new-line character (\n) or 
EOF. gets then replaces the new-line character, if read, with a null character (\0) 
before returning the line. 

Return Value If successful, gets returns its argument. A NULL pointer return value indicates an 
error or an end-of-file condition with no characters read. Use terror or feof to 
determine which of these conditions occurred. If there is an error, the value stored in 
buffer is undefined. If an end-of-file condition occurs, buffer is not changed. 

This example gets a line of input from stdin. 

#inc1ude <stdio.h> 

Idefine MAX_LINE 100 

int main(void) 

{ 

char 1 i ne[MAX_LINE]; 
char *result; 

if ((result = gets(1ine)) != NULL) { 
if (ferror(stdin)) 
perror("Error"); 

printf(“Input line : %s\n", result); 

} 

return 0; 

/**************************************************************************** 

For the following input: 

This is a test for function gets. 

The output should be: 

Input line : This a test for function gets. 
****************************************************************************/ 

} 

• “_cgets — Read String of Characters from Keyboard” on page 85 

• “fgets — Read a String” on page 230 

• “feof — Test End-of-File Indicator” on page 222 

• “ferror — Test for Read/Write Errors” on page 223 

• “fputs — Write String” on page 255 

• “getc - getchar — Read a Character” on page 296 

• “puts — Write a String” on page 473 
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• “<stdio.h>” on page 815 
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getsyntx — 

Format 

Description 

Return Value 



Return LC_SYNTAX Characters 

linclude <variant.h> 

struct variant *getsyntx(void); 

Language Level: Extension 

getsyntx determines the encoding of the special characters defined in the 
LC_SYNTAX category of the current locale, and stores the encoding values in the 
structure of type struct variant. For details of the structure type, see “<variant.h>” 
on page 821. 

Your program cannot modify the returned structure. The structure can be overwritten 
by a call to setlocale with the argument LC_ALL or LC_SYNTAX. 


getsyntx returns the pointer to the structure containing the values of the special 
characters. If the information about the special characters is not available in the 
current locale, getsyntx returns a null pointer. 

This example uses getsyntx to show the value of various special characters. 

#include <stdio.h> 

#include <variant.h> 

#include <1ocale.h> 

int main(void) 

{ 

struct variant *var; 


setlocale(LC_ALL, LC_C_USA); 
var = getsyntx(); 


printf("codeset 

%s\n", 

var->codeset 

) 

printf("backslash 

%c\n", 

var->backslash 

) 

printf("right_bracket 

%c\n", 

var->right_bracket 

) 

printf("1eft_bracket 

%c\n", 

var->l eft_bracket 

) 

printf("right_brace 

%c\n", 

var->right_brace 

) 

printf("1eft_brace 

%c\n", 

var->left brace 

) 

printf("circumflex 

%c\n", 

var->circumflex 

) 

printf("tilde 

%c\n", 

var->ti1de 

) 

printf("exclamation_mark 

%c\n", 

var->exclamation mark); 

printf("number_sign 

%c\n", 

var->number_sign 

); 
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printf("vertical_1ine 
printf("dollar_sign 
printf("commercial_at 
printf("grave_accent 
return 0; 


%c\n", var->vertical_1ine ) 
%c\n", var->dol1ar_sign ) 
%c\n", var->commercial_at ) 
%c\n", var->grave_accent ) 


/•k-k-kle-k-kle-k-klc-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-kltle-k-k'k-k-k'k-k-k-k-k-k'k'k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k 


The output should be similar to 

codeset 

IBM-850 

backsiash 

\ 

right_bracket 

] 

1eft_bracket 

[ 

right_brace 

} 

left brace 

{ 

circumflex 

A. 

ti 1 de 

~ 

exclamation mark 

1 

number_sign 

# 

vertical_line 

1 

dol1ar_sign 

$ 

commercial at 

0 

grave_accent 

' 


•k‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k-k-k-k-k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k , k-k-k-k-k-k‘k-k-k‘k-k-k^ 

} 



“setlocale — Set Locale” on page 530 
“<locale.h>” on page 806 
“<variant.h>” on page 821 
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getTIBvalue — Get Thread Information Block Value 

Format linclude <builtin.h> 

unsigned long _getTIBvalue(const unsigned int offset ); 

Description Language Level: Extension 

_getTIBvalue retrieves an unsigned long value from the thread information block 
(TIB) at the offset specified. The selector value for the TIB belonging to the 
current thread of execution is stored in the FS segment register. You should use the 
offsetof macro to calculate offset. 

Note: _getTIBval ue is a built-in function, which means it is implemented as an 
inline instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _getTIBval ue. 

• You cannot parenthesize a call to _getTIBval ue. (Parentheses specify a call to 
the function's backing code, and _getTIBvalue has none.) 

Return Value _getTIBval ue returns an unsigned long value from the TIB. There is no error 

return value and _getTIBvalue does not set errno. If offset is too large, it will 
cause an access violation when running the program. 

This example prints out all the values in the TIB structure. 

Idefine INCL_D0S 
#inc1ude <os2.h> 

#inc1ude <bui1tin.h> 

#inc1ude <stdio.h> 

#inc1ude <stddef,h> 

int main(void) 

{ 

printf("Values in Thread Information Block are:\n\n" ); 

printf("Exception chain pointer: %lx\n", 

_getTIBvalue(offsetof(TIB, tib_pexchain))); 
printf("Base stack address: %lx\n", 

_getTIBvalue(offsetof(TIB, tib_pstack))); 
printf("End of stack address: %1x\n", 

_getTIBvalue(offsetof(TIB, tib_pstacklimit))); 
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printf("System specific TIB pointer: %p\n", 

_getTIBvalue(offsetof(TIB, tib_ptib2))); 
printf("Version number: %lu\n", 

_getTIBvalue(offsetof(TIB, tib_versi on))); 
printf("Ordinal number: %lu\n", 

_getTIBvalue(offsetof(TIB, tib_ordinal))); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

Values in Thread Information Block are: 

Exception chain pointer: 38844 
Base stack address: 30000 
End of stack address: 38860 
System specific TIB pointer: 50048 
Version number: 20 
Ordinal number: 122 

****************************************************************************/ 

} 



“_threadstore — Access Thread-Specific Storage” on page 665 
“<builtin.h>” on page 801 
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getwc — Read Wide Character from Stream 

Format linclude <stdio.h> 

linclude <wchar.h> 
wint_t getwc(FILE *stream); 

Description Language Level: ANSI 93, XPG4 

getwc reads the next multibyte character from stream , converts it to a wide 
character, and advances the associated file position indicator for stream. 

getwc is equivalent to fgetwc except that, if it is implemented as a macro, it can 
evaluate stream more than once. Therefore, the argument should never be an 
expression with side effects. 

The behavior of getwc is affected by the LC_CTYPE category of the current locale. If 
you change the category between subsequent read operations on the same stream, 
undefined results can occur. 

Using non-wide-character functions with getwc on the same stream results in 
undefined behavior. 

After calling getwc, flush the buffer or reposition the stream pointer before calling a 
write function for the stream, unless EOF has been reached. After a write operation 
on the stream, flush the buffer or reposition the stream pointer before calling getwc. 

Return Value getwc returns the next wide character from the input stream, or WEOF. If an error 
occurs, getwc sets the error indicator. If getwc encounters the end-of-file, it sets the 
EOF indicator. If an encoding error occurs during conversion of the multibyte 
character, getwc sets errno to EILSEQ. 

Use terror or feof to determine whether an error or an EOF condition occurred. 

EOF is only reached when an attempt is made to read past the last byte of data. 
Reading up to and including the last byte of data does not turn on the EOF indicator. 

This example opens a file and uses getwc to read wide characters from the file. 

#inc1ude <errno.h> 

#inc1ude <stdio.h> 

#inc1ude <wchar.h> 

int main(void) 

{ 

FILE *stream; 
wint_t wc; 

if (NULL == (stream = fopen("getwc.dat", "r"))) { 
printf("Unable to open: \"getwc.dat\".\n"); 
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exit(l); 

} 


errno = 0; 

while (WEOF !=(wc = getwc(stream))) 
printf("wc = %lc\n", wc); 

if (EILSEQ == errno) { 

printf("An invalid wide character was encountered.\n"); 
exit(l); 

} 

fclose(stream); 
return 0; 

/**************************************************************************** 
Assuming the file getwc.dat contains: 

Hel1o world! 



The output should be: 

wc = H 
wc = e 
wc = 1 
wc = 1 

WC = 0 

****************************************************************************/ 

} 

• “fgetwc — Read Wide Character from Stream” on page 232 

• “getwchar — Get Wide Character from stdin” on page 317 

• “getc - getchar — Read a Character” on page 296 

• “_getch - _getche — Read Character from Keyboard” on page 298 

• “putwc — Write Wide Character” on page 474 

• “<stdio.h>” on page 815 

• “<wchar.h>” on page 821 
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getwchar — 

Format 

Description 


Return Value 



Get Wide Character from stdin 

linclude <wchar.h> 
wint_t getwchar(void); 

Language Level: ANSI, SAA, XPG4 

getwchar reads the next multibyte character from stdin, converts it to a wide 
character, and advances the associated file position indicator for stdin. A call to 
getwchar is equivalent to a call to getwc(stdin). 

The behavior of getwchar is affected by the LC_CTYPE category of the current 
locale. If you change the category between subsequent read operations on the same 
stream, undefined results can occur. 

Using non-wide-character functions with getwchar on the same stream results in 
undefined behavior. 

getwchar returns the next wide character from stdin or WEOF. If getwchar 
encounters EOF, it sets the EOF indicator for the stream and returns WEOF. If a 
read error occurs, the error indicator for the stream is set and getwchar returns 
WEOF. If an encoding error occurs during the conversion of the multibyte character 
to a wide character, getwchar sets errno to EILSEQ and returns WEOF. 

Use terror or feof to determine whether an error or an EOF condition occurred. 
EOF is only reached when an attempt is made to read past the last byte of data. 
Reading up to and including the last byte of data does not turn on the EOF indicator. 

This example uses getwchar to read wide characters from the keyboard, then prints 
the wide characters. 
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#include <errno.h> 

#include <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

wint_t wc; 
errno = 0; 

while (WEOF ! = (wc = getwchar())) 
printf("wc = %lc\n", wc); 

if (EILSEQ == errno) { 

printf("An invalid wide character was encountered.\n"); 
exit(l); 

} 

return 0; 

Assuming you enter: abcde^Z (note: is CNTRL-Z) 

The output should be: 


wc = a 
wc = b 
wc = c 
wc = d 
wc = e 

■k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-kle-k-k'k-k-k-k-k-k-k-k-k'k-k-klck-k-k-k-k-k-k-k'k-k-k'k-k-k/ 

) 



“fgetc — Read a Character” on page 225 

“_fgetchar — Read Single Character from stdin” on page 227 

“getc - getchar — Read a Character” on page 296 

“_getch - _getche — Read Character from Keyboard” on page 298 

“getwc — Read Wide Character from Stream” on page 315 

“<wchar.h>” on page 821 
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getwmccol 1 — Get Next Collating Element from Wide String 

Format linclude <collate.h> 

linclude <wchar.h> 
col lei_t getwmccol1(wchar_t **src); 

Description Language Level: Extension 

getwmccol 1 finds the first sequence of wide characters in the array pointed to by src 
that constitute a valid multi-wide-character collating element. It then produces the 
col 1 el _t value that corresponds to that collating element. It also changes src to 
point to the next byte following that collating element. 


Return Value getwmccoll returns the col lei _t value that represents the collating element found. 

If the object pointed to by src is a null pointer or points to a null wide character, 
getwmccol 1 returns 0. If the object pointed to by src points to an invalid wide 
character, getwmccol 1 returns -1 and sets errno to EILSEQ. 



This example uses getwmccol 1 to find the first collating element in the wide string s. 

#inc1ude <stdio.h> 

#include <1ocale.h> 

#include <col1 ate.h> 

#include <wchar.h> 


int main(void) 

{ 

wchar_t s[] = L"\x8141\x64"; 
wchar_t *str = s; 
collel_t x; 

if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 

printf("Setlocale(LC_ALL, \"ja_jp.ibm-932\") failed.\n"); 
exit(l); 

} 

x = getwmccol 1 (&str); 

printf("getwmccol1(\"%s\")\n", s); 

printf(" returns: Ox%x\n", x); 

printf(" remainder of string: <%s>\n", str); 

return 0; 

/**************************************************************************** 
The output should be similar to : 

getwmccol1("A d") 
returns: 0x8141 
remainder of string: <d> 

****************************************************************************/ 

} 



“ccl ass — Return Characters in Character Class” on page 82 

“col 1 equi v — Return List of Equivalent Collating Elements” on page 101 
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• “col 1 order — Return List of Collating Elements” on page 103 

• “col 1 range — Calculate Range of Collating Elements” on page 105 

• “colltostr — Return String for Collating Element” on page 107 

• “getmccol 1 — Get Next Collating Element from String” on page 306 

• “ismccollel —Identify Multi-Character Collating Element” on page 358 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “strtocol 1 — Return Collating Element for String” on page 619 

• “<collate.h>” on page 802 

• “<wchar.h>” on page 821 
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gmtime — Convert Time 

Format linclude <time.h> 

struct tm *gmtime(const time_t *time ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

The gmtime function breaks down the time value and stores it in a tm structure, 
defined in time.h. The structure pointed to by the return value reflects Coordinated 
Universal Time, not local time. The value time is usually obtained from a call to 
time. 


The fields of the tm structure include: 


tm_sec 

tm_min 

tm_hour 

tmjnday 

tmjnon 

tm_year 

tm_wday 

tm_yday 

tm isdst 


Seconds (0-61) 

Minutes (0-59) 

Hours (0-23) 

Day of month (1-31) 

Month (0-11; January = 0) 

Year (current year minus 1900) 

Day of week (0-6; Sunday = 0) 

Day of year (0-365; January 1=0) 

Zero if Daylight Saving Time is not in effect; positive if Daylight 
Saving Time is in effect; negative if the information is not 
available. 


Return Value gmtime returns a pointer to the resulting tm structure. It returns NULL if 
Coordinated Universal Time is not available. 


Notes: 

1. The range (0-61) for tm_sec allows for as many as two leap seconds. 

2. The gmtime and local time functions may use a common, statically allocated 
buffer for the conversion. Each call to one of these functions may alter the result 
of the previous call. 

3. The time and date functions begin at 00:00:00 Coordinated Universal Time, 
January 1, 1970. 



This example uses gmtime to adjust a time_t representation to a Coordinated 
Universal Time character string, and then converts it to a printable string using 
asctime. 
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#include <stdio.h> 
#include <time.h> 


int main(void) 

{ 

time_t Itime; 
time(&ltime); 

printf("Coordinated Universal Time is %s\n", asctime(gmtime(&l time))); 
return 0; 

/**************************************************************************** 

The output should be similar to: 


Coordinated Universal Time is Mon Sep 16 21:44 1995 


} 


/ 



“asctime — Convert Time to Character String” on page 55 
“ctime — Convert Time to Character String” on page 129 
“localtime — Convert Time” on page 385 
“mktime — Convert Local Time” on page 438 
“t i me — Determine Current Time” on page 666 
“<time.h>” on page 819 
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_heap_check 

Format 

Description 


Return Value 



— Validate Default Memory Heap 

linclude <stdlib.h> /* also in <malloc.h> */ 
void _heap_check(void); 

Language Level: Extension 

_heap_check checks all memory blocks in the default heap that have been allocated 
or freed using the debug memory management functions (_debug_calloc, 
_debug_mal 1 oc, and so on). _heap_check checks that your program has not 
overwritten freed memory blocks or memory outside the bounds of allocated blocks. 

When you call a debug memory management function (such as _debug_mal 1 oc), it 
calls _heap_check automatically. You can also call _heap_check explicitly. Place 
calls to _heap_check throughout your code, especially in areas that you suspect have 
memory problems. 

Calling _heap_check frequently (explicitly or through the debug memory functions) 
can increase your program's memory requirements and decrease its execution speed. 
To reduce the overhead of heap-checking, you can use the DDE4_HEAP_SKIP 
environment variable to control how often the functions check the heap. For 
example: 

SET DDE4_HEAP_SKIP= 10 

specifies that every tenth call to any debug memory function (regardless of the type 
or heap) checks the heap. Explicit calls to _heap_check are always performed. For 
more details on DDE4_HEAP_SKIP, see “Skipping Heap Checks” in the 
Programming Guide. 

To use _heap_check and the debug memory management functions, you must 
compile with the debug memory (/Tm) compiler option. 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Heap-specific and tiled versions of this function (_uheap_check and _theap_check) 
are also available. _heap_check always checks the default heap. 

There is no return value. 

This example allocates 5000 bytes of storage, and then attempts to write to storage 
that was not allocated. The call to _heap_check detects the error, generates several 
messages, and stops the program. 
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#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = malloc(5000))) { 

puts("Could not allocate memory block."); 
return EXIT_FAILURE; 

} 



*(ptr-l) = 1 a’; /* overwrites storage that was not allocated */ 

_heap_check(); 

puts("_heap_check did not detect that a memory block was overwritten."); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

Header information of object 0x00073890 was overwritten at 0x0007388c. 

The first eight bytes of the memory block (in hex) are: AAAAAAAAAAAAAAAA. 

This memory block was (re)allocated at line number 8 in _heap_check.c. 

Heap state was valid at line 8 of _heap_check.c. 

Memory error detected at line 14 of _heap_check.c. 
****************************************************************************/ 

• Memory Management in the Programming Guide 

• Debugging Your Heaps in the Programming Guide 

• “Differentiating between Memory Management Functions” on page 28 

• “_debug_cal loc — Allocate and Initialize Memory” on page 139 

• “_debug_free — Release Memory” on page 141 

• “_debug_heapmi n — Release Unused Memory in the Default Heap” on 
page 143 

• “_debug_mal 1 oc — Allocate Memory” on page 145 

• “_debug_real 1 oc — Reallocate Memory Block” on page 147 

• “_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 

• “_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

• “_heapchk — Validate Default Memory Heap” on page 325 

• “_uheap_check — Validate User Memory Heap” on page 705 

• “<malloc.h>” on page 810 

• “<stdlib.h>” on page 816 
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_heapchk — 

Format 

Description 

Return Value 



Validate Default Memory Heap 

linclude <malloc.h> 
int _heapchk(void); 

Language Level: Extension 

_heapchk checks the default storage heap for minimal consistency by checking all 
allocated and freed objects on the heap. 

A heap-specific version of this function, _uheapchk, is also available. 

Note: Using the _heapchk, _heapset, and _heap_wal k functions (and their 
heap-specific equivalents) may add overhead to each object allocated from the heap. 

_heapchk returns one of the following values, defined in <malloc.h>: 

_HEAPBADBEGIN The heap specified is not valid. (Only occurs if you changed 
the default heap and then later closed or destroyed it.) 
_HEAPBADNODE A memory node is corrupted, or the heap is damaged. 
_HEAPEMPTY The heap has not been initialized. 

_HEAPOK The heap appears to be consistent. 

This example performs some memory allocations, then calls _heapchk to check the 
heap. 

#include <stdlib.h> 

#inc1ude <stdio.h> 

#include <mal1oc.h> 

int main(void) 

{ 

char *ptr; 
int rc; 

if (NULL == (ptr = malloc(10))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

*(ptr - 1) = 'x'; /* overwrites storage that was not allocated */ 
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if (_HEAPOK != (rc = _heapchk())) { 
switch(rc) { 

case _HEAPEMPTY: 

puts("The heap has not been initialized."); 
break; 

case _HEAPBADNODE: 

puts("A memory node is corrupted or the heap is damaged."); 
break; 

case _HEAPBADBEGIN: 

puts("The heap specified is not valid."); 
break; 

} 

exit(rc); 

} 

free(ptr); 
return 0; 

^•k-k-k-k-k-k'k-k-k'k-k-k'k-k-kic-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-kic-k-k-k-k-k-k-k-k-k-k-k-k 

The output should be similar to : 

A memory node is corrupted or the heap is damaged. 

} 



“Managing Memory” in the Programming Guide 
“_uheapchk — Validate Memory Heap” on page 707 
“_heapmin — Release Unused Memory from Default Heap” on page 327 
“_heapset — Validate and Set Default Heap” on page 328 
“_heap_wal k — Return Information about Default Heap” on page 330 
“<malloc.h>” on page 810 
“<umalloc.h>” on page 820 
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heapmi n — Release Unused Memory from Default Heap 

Format linclude <std1ib.h> /* also in emailoc.h> */ 

int _heapmin(void); 

Description Language Level: Extension 

_heapmi n returns all unused memory from the default runtime heap to the operating 
system. 

Heap-specific, tiled, and debug versions of this function (_uheapmin, _theapmin, and 
_debug_heapmi n) are also available. _heapmin always operates on the default heap. 

Note: If you create your own heap and make it the default heap, _heapmin calls the 
release function that you provide to return the memory. 


Return Value _heapmi n returns 0 if successful; if not, it returns -1. 

This example shows how to use the _heapmin function. 

#inc1ude <stdio.h> 

#inc1ude <stdlib.h> 

int main(void) 

{ 

if (_heapmin()) 

printf("_heapmin failed.\n"); 
el se 

printf("_heapmin was successful,\n"); 
return 0; 

/**************************************************************************** 
The output should be: 

_heapmin was successful. 

****************************************************************************/ 

i 




Managing Memory in the Programming Guide 

“_debug_heapmin — Release Unused Memory in the Default Heap” on 
page 143 

“_debug_theapmi n — Release Unused Tiled Memory” on page 153 
“_debug_uheapmi n — Release Unused Memory in User Heap” on page 162 
“_theapmin — Release Unused Tiled Memory” on page 663 
“_uheapmin — Release Unused Memory in User Heap” on page 709 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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_heapset — 

Format 

Description 


Return Value 



Validate and Set Default Heap 

linclude <malloc.h> 

int _heapset(unsigned int fill); 

Language Level: Extension 

_heapset checks the default storage heap for minimal consistency by checking all 
allocated and freed objects on the heap (similar to _heapchk). It then sets each byte 
of the heap's free objects to the value of fill. 

Using _heapset can help you locate problems where your program continues to use a 
freed pointer to an object. After you set the free heap to a specific value, when your 
program tries to interpret the set values in the freed object as data, unexpected results 
occur, indicating a problem. 

A heap-specific version of this function, _uheapset, is also available. 

Note: Using the _heapchk, _heapset, and _heap_wal k functions (and their 
heap-specific equivalents) may add overhead to each object allocated from the heap. 

_heapset returns one of the following values, defined in <malloc.h>: 

_HEAPBADBEGIN The heap specified is not valid; it may have been closed or 
destroyed. 

_HEAPBADNODE A memory node is corrupted, or the heap is damaged. 
_HEAPEMPTY The heap has not been initialized. 

_HEAPOK The heap appears to be consistent. 

This example allocates and frees memory, then uses _heapset to set the free heap to 
X. It checks the return code from _heapset to ensure the heap is still valid. 
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#include <stdlib. h> 

#include <stdio.h> 

#include <mal1oc.h> 

int main (void) 

{ 

char *ptr; 
int rc; 

if (NULL == (ptr = malloc(10))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 1 A 1 ,5); 
free(ptr); 

if (_HEAP0K != (rc = _heapset( 1 X 1 ))) { 
switch(rc) { 

case _HEAPEMPTY: 

puts("The heap has not been initialized."); 
break; 

case _HEAPBADNODE: 

puts("A memory node is corrupted or the heap is damaged."); 
break; 

case _HEAPBADBEGIN: 

puts("The heap specified is not valid."); 
break; 

} 

exit(rc); 

} 

return 0; 


• “Managing Memory” in the Programming Guide 

• “_heapchk — Validate Default Memory Heap” on page 325 

• “_heapmin — Release Unused Memory from Default Heap” on page 327 

• “_heap_wal k — Return Information about Default Heap” on page 330 

• “_uheapset — Validate and Set Memory Heap” on page 711 

• “<malloc.h>” on page 810 

• “<umalloc.h>” on page 820 
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_heap_walk 

Format 

Description 


- Return Information about Default Heap 

linclude <malloc.h> 

int _heap_walk(int (*calIback^fn )(const void *object, size_t size, 

int flag, int status, 

const char* file, int line ) ); 


Language Level: Extension 

_heap_wal k traverses the default heap, and for each allocated or freed object, it calls 
the cal Iback^fn function that you provide. For each object, it passes your function: 

object A pointer to the object. 
size The size of the object. 

flag The value _USEDENTRY if the object is currently allocated, or 

_FREEENTRY if the object has been freed. (Both values are defined in 
<malloc.h>.) 

status One of the following values, defined in <mal loc.h>, depending on the 
status of the object: 

_HEAPBADBEGIN The heap specified is not valid; it may have been 
closed or destroyed. 

_HEAPBADNODE A memory node is corrupted, or the heap is 
damaged. 

_HEAPEMPTY The heap has not been initialized. 

_HEAPOK The heap appears to be consistent. 

file The name of the file where the object was allocated. 

I ine The line where the object was allocated. 

_heap_wal k provides information about all objects, regardless of which memory 
management functions were used to allocate them. However, the file and line 
information are only available if the object was allocated and freed using the debug 
versions of the memory management functions. Otherwise, fi le is NULL and l ine 
is 0. 


_heap_wal k calls cal Iback^fn for each object until one of the following occurs: 

• All objects have been traversed. 

• callback^fn returns a nonzero value to _heap_wal k. 

• It cannot continue because of a problem with the heap. 

You may want to code your callback^fn to return a nonzero value if the status of 
the object is not _HEAPOK. Even if callback_fn returns 0 for an object that is 
corrupted, _heap_wal k cannot continue because of the state of the heap and returns to 
its caller. 
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You can use cal Iback^fn to process the information from _heap_wal k in various 
ways. For example, you may want to print the information to a file or use it to 
generate your own error messages. You can use the information to look for memory 
leaks and objects incorrectly allocated or freed from the heap. It can be especially 
useful to call _heap_wal k when _heapchk returns an error. 

A heap-specific version of this function, _uheap_wal k, is also available. 

Notes: 

1. Using the _heapchk, _heapset, and _heap_wal k functions (and their 
heap-specific equivalents) may add overhead to each object allocated from the 
heap. 

2. _heap_wal k locks the heap while it traverses it, to ensure that no other 
operations use the heap until _heap_wal k finishes. As a result, in your 

cal lback_fn, you cannot call any critical functions in the runtime library, either 
explicitly or by calling another function that calls a critical function. See the 
Programming Guide for a list of critical functions. 


Return Value _heap_wal k returns the last value of status to the caller. 



This example allocates some memory, then uses _heap_wal k to walk the heap and 
pass information about allocated objects to the callback function cal 1 back_function. 
cal 1 back_function then checks the information and keeps track of the number of 
allocated objects. 


#include <stdlib.h> 

#include <stdio.h> 

#include <mal1oc.h> 

int callback_function(const void *pentry, size_t sz, int useflag, int status, 
const char *filename, size_t line) 

{ 

if (_HEAP0K != status) { 

puts("status is not _HEAP0K."); 
exit(status); 

} 

if ( USEDENTRY == useflag) 

printf("allocated %p %u\n", pentry, sz); 
el se 

printf("freed %p %u\n", pentry, sz); 

return 0; 
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int main(void) 

{ 

char *pl, *p2, *p3; 

if (NULL == (pi = mal1oc(100)) 

NULL == (p2 = malloc(20O)) 

NULL == (p3 = malloc(30O))) { 
puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

free(p2); 

puts("usage address size\n- - -"); 

_heap_walk(cal1back_function); 

free(pl); 
free(p3); 
return 0; 

/■********************************************************■******'*'**'***'***'*'**'** 


The output 

should be 

simi 

usage 

address 

size 

al1ocated 

73A10 

300 

al1ocated 

738B0 

100 

freed 

73920 

224 


■k , k-k-k‘k-k-k‘k-k-k‘k-k-k-k'k-k-k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k1e-k-k‘k-k-k‘k-k-k/ 



“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“_heapchk — Validate Default Memory Heap” on page 325 
“_heapmin — Release Unused Memory from Default Heap” on page 327 
“_heapset — Validate and Set Default Heap” on page 328 
“_uheap_wal k — Return Information about Memory Heap” on page 713 
“<malloc.h>” on page 810 
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hypot — Calculate Hypotenuse 

Format linclude <math.h> 

double hypot(double sidel, double side2); 

Description Language Level: SAA, XPG4 

hypot calculates the length of the hypotenuse of a right-angled triangle based on the 
lengths of two sides sidel and side2. A call to hypot is equivalent to: 

sqrt (sidel * sidel + side2 * side2); 


Return Value hypot returns the length of the hypotenuse. If an overflow results, hypot sets 

errno to ERANGE and returns the value HUGEJVAL. If an underflow results, hypot 
sets errno to ERANGE and returns zero. 



This example calculates the hypotenuse of a right-angled triangle with sides of 3.0 
and 4.0. 

#include <math.h> 


int main(void) 

{ 

double x,y,z; 


x = 3.0; 
y = 4.0; 

z = hypot(x, y); 

printf("The hypotenuse of the triangle with sides %lf and %lf" 
" i s %1f\n", x, y, z); 
return 0; 


/**************************************************************************** 
The output should be: 

The hypotenuse of the triangle with sides 3.000000 and 4.000000 is 5.000000 
****************************************************************************/ 
i 



“_fsqrt — Calculate Square Root” on page 280 
“sqrt — Calculate Square Root” on page 556 
“<math.h>” on page 811 
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i conv — Convert Characters to New Code Set 

Format linclude <iconv.h> 

size_t iconv(iconv_t cd, char **inbuf, size_t *insize, 
char **outbuf, size_t *outsize ); 

Description Language Level: XPG4 

i conv converts a sequence of characters in one encoded character set, in the array 
indirectly pointed to by inbuf and converts them to a sequence of corresponding 
characters in another encoded character set. It stores the corresponding sequence in 
the array indirectly pointed to by outbuf. cd is the conversion descriptor returned 
from i conv_open that describes which codesets are used in the conversion. 

inbuf points to a variable that points to the first character of input, and insize 
indicates the number of bytes of input, outbuf points to a variable that points to the 
first character of output, and outsize indicates the number of available bytes for 
output. 

As iconv converts the characters, it updates the variable pointed to by inbuf to point 
to the next byte in the input buffer, and updates the variable pointed to by out but to 
the byte following the last successfully converted character. It also decrements 
insize and outsize to reflect the number of bytes of input remaining and the 
number of bytes still available for output, respectively. If the entire input string is 
converted, insize will be 0; if an error stops the conversion, insize will have a 
nonzero value. 

If it encounters a valid input character that does not have a defined conversion in cd , 
i conv translates the character to the ASCII value 0xla. 

Sharing a conversion descriptor in iconv across multiple threads may result in 
undefined behavior. 


Return Value i conv returns the number of characters successfully converted. If an error occurs, 
conversion stops after the previous successfully converted character; iconv returns 
(size_t)-l, and sets errno to one of the following values; 

Value Meaning 

EILSEQ A sequence of input bytes does not form a valid character in the 
specified encoded character set. 

E2BIG outbuf is not large enough to hold the converted value. 

EINVAL The input ends with an incomplete character. 

EBADF cd is not a valid conversion descriptor. 
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This example converts an array of characters coded in encoded character set IBM-850 
(in in) to an array of characters coded in encoded character set IBM-037 (stored in 
out). 


#include <iconv.h> 
#include <stdlib.h> 
#include <stdio.h> 


int main(void) 
{ 

const char 

const char 

i conv_t 

char 

size_t 

char 

char 

size_t 

char 

i nt 


fromcode [] = "IBM-850"; 
tocodef] = "IBM-037"; 
cd; 

in[] = "ABCDEabcde"; 
in_size; 

*inptr = in; 
out[100]; 

out_size = sizeof(out); 
*outptr = out; 
i; 


if ((iconv_t)(-1) == (cd = iconv_open(tocode, fromcode))) { 
printf("Failed to iconv_open %s to %s.\n", fromcode, tocode); 
exit(EXIT_FAI ; 

} 

/* Convert the first 3 characters in array "in". */ 

in_size = 3; 

if ((size_t)(-1) == iconv(cd, &inptr, &in_size, &outptr, &out_size)) { 
printf("Fail to convert first 3 characters to new code set.\n"); 
exit(EXITFAILURE); 

} 

/* Convert the rest of the characters in array "in". */ 

in_size = sizeof(in) - 3; 

if ((size_t)(-1) == iconv(cd, &inptr, &in_size, &outptr, &out_size)) { 
printf("Fail to convert the rest of the characters to new code set.\n"); 
exit(EXITFAILURE); 

} 

*outptr = 1 \0' ; 

printf("The hex representation of string %s are:\n In codepage %s ==> ", 
in, fromcode); 

for (i = 0; in[i] != 1 \0'; i++) { 
printf("0x%02x ", in[i]); 

} 

printf("\n In codepage %s ==> ", tocode); 

for (i = 0; out[i] != 1 \0 1 ; i++) { 
printf("0x%02x ", out[i]); 
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if (-1 == iconv_close(cd)) { 

printf("Fail to iconv_close.\n"); 
exit(EXIT_FAILURE); 

} 

return 0; 

/**************************************************************************** 

The output should be similar to : 

The hex representation of string ABCDEabcde are: 

In codepage IBM-850 ==> 0x41 0x42 0x43 0x44 0x45 0x61 0x62 0x63 0x64 0x65 
In codepage IBM-037 ==> 0xcl 0xc2 0xc3 0xc4 0xc5 0x81 0x82 0x83 0x84 0x85 
****************************************************************************/ 

} 



“i Conv_c1 ose — Remove Conversion Descriptor” on page 337 
“iconv_open — Create Conversion Descriptor” on page 338 
“setlocale — Set Locale” on page 530 
“Introduction to Locale” in the Programming Guide 
“<locale.h>” on page 806 
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iconv_close 

Format 

Description 

Returned 

Value 



— Remove Conversion Descriptor 

linclude <iconv.h> 

int iconv_close(iconv_t cd ); 

Language Level: XPG4 

iconv_close deallocates the conversion descriptor cd and all other associated 
resources allocated by the iconv_open function. 

If successful, iconv_close returns 0. Otherwise, iconv_close returns -1 is 
returned and sets errno to indicate the cause of the error. If cd is not a valid 
descriptor, an error occurs and iconv_close sets errno to EBADF. 

This example shows how you would use iconv_close to remove a conversion 
descriptor. 

#inc 1 ude <iconv.h> 

#inc 1 ude <stdlib.h> 

#inc 1 ude <stdio.h> 

int main(void) 

{ 

const char fromcode[] = "IBM-850"; 
const char tocode[] = "IBM-863"; 
iconv_t cd; 

if ((iconv_t)(-1) == (cd = iconv_open(tocode, fromcode))) { 
printf("Failed to iconv_open %s to %s.\n", fromcode, tocode); 
exit(EXIT_FAILURE); 

} 

if (-1 == iconv_close(cd)) { 

printf("Fail to iconv_close.\n"); 
exit(EXIT_FAILURE); 

} 

return 0; 

} 

• “i conv — Convert Characters to New Code Set” on page 334 

• “i conv_open — Create Conversion Descriptor” on page 338 

• “setl ocal e — Set Locale” on page 530 

• “Introduction to Locale” in the Programming Guide 

• “<locale.h>” on page 806 
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iconv_open 

Format 

Description 


Returned 

Value 



- Create Conversion Descriptor 

#i ncl tide <iconv.h> 

iconv_t iconv_open(const char *tocode, const char *fromcode)\ 

Language Level: XPG4 

i conv_open performs all the initialization needed to convert characters from the 
encoded character set specified in the array pointed to by fromcode to the encoded 
character set specified in the array pointed to by tocode. It creates a conversion 
descriptor that relates the two encoded character sets. You can then use the 
conversion descriptor with the i conv function to convert characters between the 
codesets. 

The conversion descriptor remains valid until you close it with iconv_close. 

For information about the settings of fromcode , tocode , and their permitted 
combinations, see the section on internationalization in the Programming Guide. 


If successful, iconv_open returns a conversion descriptor of type iconv_t. 

Otherwise, it returns (iconv_t)-l, and sets errno to indicate the error. If you cannot 
convert between the encoded character sets specified, an error occurs and iconv_open 
sets errno to EINVAL. 

This example shows how to use iconv_open, iconv, and iconv_close to convert 
characters from one codeset to another. 


#include <iconv.h> 
#include <stdlib.h> 
#include <stdio.h> 


int main(void) 

{ 

const char 
const char 
i conv_t 
char 
size t 


fromcode[] = "IBM-932"; 
tocode[] = "IBM-930"; 
cd; 

in[] = "\x81\x40\x81\x80"; 
in_size = sizeof(in); 
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char 

*inptr = 

in; 

char 

out[100]; 


size_t 

out_size 

= sizeof(out); 

char 

*outptr = 

: out; 

i nt 

i; 



if ((iconv_t)(-1) == (cd = iconv_open(tocode, fromcode))) { 
printf("Failed to iconv_open %s to %s.\n", fromcode, tocode); 
exit(EXIT_FAILURE); 

} 

if ((size_t)(-1) == iconv(cd, &inptr, &in_size, &outptr, &out_size)) { 
printf("Fail to convert characters to new code set.\n"); 
exit(EXIT_FAILURE); 

} 

*outptr = '\0'; 

printf("The hex representation of string %s are:\n In codepage %s ==> ", 
in, fromcode); 

for (i = 0; in[i] != 1 \0'; i++) { 
printf("0x%02x ", in[i]); 

} 

printf("\n In codepage %s ==> ", tocode); 

for (i = 0; out[i] != 1 \0 1 ; i++) { 
printf("0x%02x ", out[i]) ; 

} 

if (-1 == iconv_close(cd)) { 

printf("Fail to iconv_close.\n"); 
exit(EXIT_FAILURE); 

} 

return 0; 

/**************************************************************************** 
The output should be similar to : 

The hex representation of string 0 a are: 

In codepage IBM-932 ==> 0x81 0x40 0x81 0x80 
In codepage IBM-930 ==> Ox0e 0x40 0x40 0x44 0x7b OxOf 

****************************************************************************/ 


• “i conv — Convert Characters to New Code Set” on page 334 

• “i conv_cl ose — Remove Conversion Descriptor” on page 337 

• “setl ocal e — Set Locale” on page 530 

• “Introduction to Locale” in the Programming Guide 

• “<locale.h>” on page 806 
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inp — Read Byte from Input Port 


Format 

Description 


Return Value 



linclude <conio.h> /* also in <builtin.h> */ 
int _inp(const unsigned int port); 

Language Level: Extension 

_i np reads a byte from the specified input port. The port number must be an 
unsigned int value in the range 0 to 65 535 inclusive. 

Note: _inp is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _i np. 

• You cannot parenthesize a call to _inp. (Parentheses specify a call to the 
function's backing code, and _i np has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 

_i np returns the byte value as an integer that was read from the specified port. 

There is no error return value, and _i np does not set errno. 

This example uses _inp to read a byte from a specified input port and return the data 
read. 

#include <bui1tin.h> 

#define LOWER 0 
#define UPPER 65535 

int Add1(int j); 

int g; 

enum fruit {apples=10, bananas, cantaloupes); 

int arr[] = {cantaloupes, bananas, apples); 

struct 

{ 

int i; 
char ch; 

} st; 
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int main(void) 



i 

int i; 

volatile const int c = 

0; 


i = _inp(0); 

g = inp(LOWER + 1); 

/* put the data read in a global variable 

*/ 

i = inp(apples); 

/* passing enumerated type as the 

*/ 


/* port number 

*/ 


/*- 

*/ 


/* Types of port number passed : 

*/ 


/* -- 

*/ 

i = inp(c); 

/* - constant 

*/ 

i = inp(arr[c]); 

/* - element of array 

*/ 

st.i = Add 1(c); 

/* 

*/ 

i = inp(st.i); 

/* - element of structure 

*/ 

i = inp(Add 1(LOWER)); 

/* - return value from a function call 

*/ 

i = inp(UPPER); 

/* - Idefine constant 

*/ 

i = inp(256); 

/* - the exact port number 

*/ 

return 0; 

/* ---- 

*/ 


int Addl(int j) 
{ 

j += l; 
return j; 


• “_inpw — Read Unsigned Short from Input Port” on page 344 

• “_i npd — Read Doubleword from Input Port” on page 342 

• “i satty — Test Handle for Character Device” on page 352 

• “_outp — Write Byte to Output Port” on page 450 

• “_outpw — Write Word to Output Port” on page 454 

• “_outpd — Write Double Word to Output Port” on page 452 

• “<builtin.h>” on page 801 

• “<conio.h>” on page 802 
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inpd — Read Doubleword from Input Port 

Format linclude <conio.h> /* also in <builtin.h> */ 

unsigned long _inpd(const unsigned int port); 

Description Language Level: Extension 

_i npd reads a 4-byte (doubleword) unsigned value from the specified input port. 
The port number must be an unsigned short value within the range 0 to 65 535 
inclusive. 

Note: _i npd is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _i npd. 

• You cannot parenthesize a call to _i npd. (Parentheses specify a call to the 
function's backing code, and _i npd has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 


Return Value _i npd returns the value read from the specified port. There is no error return 
value, and _inpd does not set errno. 



This example uses _inpd to read a doubleword value from the specified input port 
and return the data read. 

#include <bui1tin.h> 

#define LOWER 0 
#define UPPER 65535 

int Add1(int j); 


static long g; 

enum fruit {apples=10, bananas, cantaloupes}; 

int arr[] = {cantaloupes, bananas, apples}; 

uni on 

{ 

int i; 
char ch; 

} un; 


int main(void) 

{ 

unsigned long 1; 
volatile const int c = 0; 
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un.i = 65534; 

g = _inpd(255); /* put the 


1 = _inpd(c); 

1 = _inpd(un.i); 

1 = _inpd(Addl(cantaloupes)); 

1 = _inpd(_inp(arr[Addl(LOWER)])); 


return 0; 

} 


data read in a global variable */ 
/* =========================== */ 

/* Types of port number passed:*/ 

/* - */ 

/* - constant */ 

/* - element of union */ 

/* - return value from a */ 

/* function call */ 

/* - return value from a */ 

/* builtin function call */ 

/* - */ 


int Addl(int j) 

{ 

j += l; 
return j; 


• “_i np — Read Byte from Input Port” on page 340 

• “_inpw — Read Unsigned Short from Input Port” on page 344 

• “i satty — Test Handle for Character Device” on page 352 

• “_outp — Write Byte to Output Port” on page 450 

• “_outpw — Write Word to Output Port” on page 454 

• “_outpd — Write Double Word to Output Port” on page 452 

• “<builtin.h>” on page 801 

• “<conio.h>” on page 802 
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inpw — Read Unsigned Short from Input Port 


Format 

Description 


Return Value 



linclude <conio.h> /* also in <builtin.h> */ 
unsigned short _inpw(const unsigned int port); 

Language Level: Extension 

_i npw reads an unsigned short value from the specified input port. The port 
number must be an unsigned short value within the range 0 to 65 535 inclusive. 

Note: _inpw is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _i npw. 

• You cannot parenthesize a call to _inpw. (Parentheses specify a call to the 
function's backing code, and _inpw has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 

_i npw returns the value read from the specified port. There is no error return 
value, and _inpw does not set errno. 

This example uses _inpw to read an unsigned short value from the specified input 
port and return the data read. 

#include <bui1tin.h> 

#define LOWER 0 
#define UPPER 65535 

int Add1(int j); 

volatile short g; 

int main(void) 

{ 

volatile unsigned short s; 
volatile const int c = 0; 
int i = 65534; 
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enum fruit {apples, bananas, cantaloupes}; 
int arr[] = {cantaloupes, bananas, apples}; 


g = _inpw(LOWER); /* put the data read in a global variable */ 

s = _inpw(bananas); /* passing enumerated type */ 

/* as the port number */ 

/* =========================== */ 

/* Types of port number passed:*/ 

/* - */ 

s = _inpw(c); /* - constant */ 

s = _inpw(i+l); /* - integer */ 

s = _inpw(arr[bananas]); /* - element of array */ 

s = _inpw(_outp(UPPER,cantaloupes)); /* - return value from a */ 

/* builtin function call */ 


int Addl(int j) 

{ 

j += l; 
return j; 


• “_i np — Read Byte from Input Port” on page 340 

• “_i npd — Read Doubleword from Input Port” on page 342 

• “i satty — Test Handle for Character Device” on page 352 

• “_outp — Write Byte to Output Port” on page 450 

• “_outpw — Write Word to Output Port” on page 454 

• “_outpd — Write Double Word to Output Port” on page 452 

• “<builtin.h>” on page 801 

• “<conio.h>” on page 802 
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interrupt 


_i interrupt 

Format 

Description 


Return Value 



- Call Interrupt Procedure 

linclude <builtin.h> 

void _interrupt(const unsigned int intnum ); 

Language Level: Extension 

_i nterrupt calls the interrupt procedure specified by intnum using the INT machine 
instruction. The integer intnum must have a value within the range 0 to 255 
inclusive. 

Note: _i nterrupt is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _i nterrupt. 

• You cannot parenthesize a call to _i nterrupt. (Parentheses specify a call to the 
function's backing code, and _i nterrupt has none.) 

There is no return value, and _i nterrupt does not set errno. 

This example calls interrupt 3, which is a breakpoint. 

#include <bui1tin.h> 

int main(void) 

{ 

/* A breakpoint will occur when running this program */ 

/* within a debugger. */ 

_interrupt(3); 

return 0; 

} 

• “_disable — Disable Interrupts” on page 168 

• “_enable — Enable Interrupts” on page 194 

• “<builtin.h>” on page 801 
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i sal num to i sxdi git — Test Integer Value 


Format 


linclude <ctype.h> 

int isalnum(int c); 
int isalpha(int c); 
int iscntrl (int c); 
int isdigit (int c); 
int isgraph (int c); 
int isiower(int c); 
int isprint (int c); 
int ispunct (int c); 
int isspace(int c); 
int isupper(int c); 
int isxdigit(int c); 


/* test for: */ 

/* alphanumeric character */ 

/* alphabetic character */ 

/* control character */ 

/* decimal digit */ 

/* printable character, excluding space */ 

/* lowercase character */ 

/* printable character, including space */ 

/* nonalphanumeric printable character, excluding space */ 
/* whitespace character */ 

/* uppercase character */ 

/* hexadecimal digit */ 


Description Language Level: ANSI, SAA, POSIX, XPG4 


These functions test a given integer value c to determine if it has a certain property 
as defined by the LC_CTYPE category of your current locale. The value of c must 
be representable as an unsigned char, or EOF. 


The functions test for the following: 


isalnum 

Alphanumeric character (upper- or lowercase letter, or decimal digit), 
as defined in the locale source file in the alnum class of the 

LC_CTYPE category of the current locale. 

isalpha 

Alphabetic character, as defined in the locale source file in the alpha 
class of the LC_CTYPE category of the current locale. 

iscntrl 

Control character, as defined in the locale source file in the cntrl class 
of the LC_CTYPE category of the current locale. 

i sdigit 

Decimal digit (0 through 9), as defined in the locale source file in the 
digit class of the LC_CTYPE category of the current locale. 

i sgraph 

Printable character, excluding the space character, as defined in the 
locale source file in the graph class of the LC_CTYPE category of the 
current locale. 

i si ower 

Lowercase letter, as defined in the locale source file in the 1 ower class 
of the LC_CTYPE category of the current locale. 

i sprint 

Printable character, including the space character, as defined in the 
locale source file in the pri nt class of the LC_CTYPE category of the 
current locale. 
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Return Value 



ispunct Nonalphanumeric printable character, excluding the space character, as 
defined in the locale source file in the punct class of the LC_CTYPE 
category of the current locale. 

isspace White-space character, as defined in the locale source file in the space 
class of the LC_CTYPE category of the current locale. 

i supper Uppercase letter, as defined in the locale source file in the upper class 
of the LC_CTYPE category of the current locale. 

i sxdigi t Hexadecimal digit (0 through 9, a through f, or A through F), as 

defined in the locale source file in the xdigit class of the LC_CTYPE 
category of the current locale. 


You can redefine any character class in the LC_CTYPE category of the current 
locale, with some restrictions. See the section about the LC_CTYPE class in the 
Programming Guide for details about these restrictions. 


These functions return a nonzero value if the integer satisfies the test condition, or 0 
if it does not. 

This example analyzes all characters between 0x0 and OxFF. The output of this 
example is a 256-line table showing the characters from 0 to 255, indicating whether 
they have the properties tested for. 

#include <stdio.h> 
linclude <ctype.h> 

#include <locale.h> 

#define UPPER_LIMIT OxFF 

int main(void) 

{ 

int ch; 

setlocale(LC_ALL, LC_C_USA); 

for (ch = 0; ch <= UPPER_LIMIT; ++ch) { 
printf("%#04x ", ch); 


printf("%c". 

isprint(ch) 

? 

ch 

1 '); 

printf("%s". 

isalnum(ch) 

? 

" AN" 

■ ") 

printf("%s". 

isalpha(ch) 

? 

" A " 

■ ") 

printf("%s". 

iscntrl(ch) 

? 

" C " 

■ ") 

printf("%s". 

isdigit(ch) 

? 

" D " 

■ ") 

printf("%s". 

isgraph(ch) 

? 

" G " 

■ ") 

printf("%s". 

isiower(ch) 

? 


II II j 

printf("%s". 

ispunct(ch) 

? 

" PU" 

■ ") 
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printf("%s", isspace(ch) ? " S " 
printf("%s", isprint(ch) ? " PR" 
printf("%s", isupper(ch) ? " U " 
printf("%s", isxdigit(ch) ? " H " 
putchar('\n'); 


11 ) 
") 
") 
") 


return 0; 

/**************************************************************************** 


The output 

should 

be 

simi 1 ar 

to : 


0x20 



S 

PR 


0x21 ! 


G 

PU 

PR 


0x22 " 


G 

PU 

PR 


0x23 # 


G 

PU 

PR 


0x24 $ 


G 

PU 

PR 


0x25 % 


G 

PU 

PR 


0x26 & 


G 

PU 

PR 


0x27 1 


G 

PU 

PR 


0x28 ( 


G 

PU 

PR 


0x29 ) 


G 

PU 

PR 


0x2a * 


G 

PU 

PR 


0x2b + 


G 

PU 

PR 


0x2c , 


G 

PU 

PR 


0x2d - 


G 

PU 

PR 


0x2e . 


G 

PU 

PR 


0x2f / 


G 

PU 

PR 


0x30 0 AN 

D 

G 


PR 

H 

0x31 1 AN 

D 

G 


PR 

H 

0x32 2 AN 

D 

G 


PR 

H 

0x33 3 AN 

D 

G 


PR 

H 

0x34 4 AN 

D 

G 


PR 

H 

0x35 5 AN 

D 

G 


PR 

H 

0x36 6 AN 

D 

G 


PR 

H 

0x37 7 AN 

D 

G 


PR 

H 

0x38 8 AN 

D 

G 


PR 

H 

0x39 9 AN 

D 

G 


PR 

H 


****************************************************************************/ 


• “isascii —Test Integer Values” on page 350 

• “_i scsym - _i scsymf — Test Integer” on page 356 

• “i swal num to i swxdigi t — Test Wide Integer Value” on page 360 

• “setl ocal e — Set Locale” on page 530 

• “tolower - toupper — Convert Character Case” on page 676 

• “_toascii - _tolower - _toupper — Convert Character” on page 673 

• “<ctype.h>” on page 802 
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Test Integer Values 

#include <ctype.h> 
int isascii(int c); 

Description Language Level: XPG4, Extension 

i sasci i tests if an integer is within the ASCII range. This macro assumes that the 
system uses the ASCII character set. 

Note: In earlier releases of C Set ++, isascii began with an underscore (_isascii). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _i sasci i to i sasci i for you. 

Return Value i sasci i returns a nonzero value if the integer is within the ASCII set, and 0 if it is 
not. 

This example tests the integers from 0x7c to 0x82, and prints the corresponding ASCII 
character if the integer is within the ASCII range. 

#include <stdio.h> 

#include <ctype.h> 

int main(void) 

{ 

int ch; 

for (ch = 0x7c; ch <= 0x82; ch++) { 
printf("%#04x ", ch); 

if (isascii (ch)) 

printf("The ASCII character is %c\n", ch); 
el se 

printf("Not an ASCII character\n"); 

} 

return 0; 

/•k-ki<‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-ki(-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-ki<‘k-k-k-k-ki<‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k 

The output should be: 

0x7c The ASCII character is | 

0x7d The ASCII character is } 

0x7e The ASCII character is 

0x7f The ASCII character is A 

0x80 Not an ASCII character 

0x81 Not an ASCII character 

0x82 Not an ASCII character 

■k-k-k-klt-k-k-k-k-kle-k-kle-k-k-k-k-k'k-k-k-k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-klck-k-k-kick-k-k-k-k-k'k-kit/ 

) 

• “i sal num to i sxdigi t — Test Integer Value” on page 347 

• “_i scsym - _i scsymf — Test Integer” on page 356 

• “iswalnum to iswxdigit — Test Wide Integer Value” on page 360 

• “_toascii - _tolower - _toupper — Convert Character” on page 673 
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Format 



isascii 


tolower - toupper — Convert Character Case” on page 676 
<ctype.h>” on page 802 
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isatty 


isatty — Test Handle for Character Device 

Format linclude <io.h> 

int isatty(int handle ); 

Description Language Level: XPG4, Extension 

i satty determines whether the given handle is associated with a character device (a 
keyboard, display, or printer or serial port). 

Note: In earlier releases of C Set ++, isatty began with an underscore (_isatty). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _isatty to isatty for you. 

Return Value i satty returns a nonzero value if the device is a character device. Otherwise, the 
return value is 0. 

This example opens the console and determines if it is a character device: 

#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl,h> 
linclude <sys\stat.h> 

int main(void) 

{ 

int fh,result; 

if (-1 == (fh = open("C0N", 0_RDWR, (SIREAD|S_IWRITE)))) { 
perror("Error opening console\n"); 
return EXIT_FAILURE; 

} 

result = isatty(fh); 
if (0 != result) 

printf("CON is a character device.\n"); 
else 

printf("CON is not a character device.\n"); 
close(fh); 
return 0; 

/•k-k-k-k-k-k-k-k-k'k-k-kle-k-k-k-k-k'k-k-k'k-k-kle-k-kle-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-kie-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k 

The output should be: 

CON is a character device. 

ic'k-k-kle-k-kle-k-k'k-k-kle-kltle-k-klc-k-k-k-k-kle-klt'k'k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-klt'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k'k/ 

} 

• “_i np — Read Byte from Input Port” on page 340 

• “_i npd — Read Doubleword from Input Port” on page 342 

• “_inpw — Read Unsigned Short from Input Port” on page 344 

• “_outp — Write Byte to Output Port” on page 450 

• “_outpd — Write Double Word to Output Port” on page 452 

352 VisualAge C++ C Library Reference 






isatty 


• “_outpw — Write Word to Output Port” on page 454 

• “<io.h>” on page 804 
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isblank — Test for Blank Character Classification 

Format linclude <ctype.h> 

int isblank(int c); 

Description Language Level: Extension 

i sbl ank tests whether the current LC_CTYPE locale category assigns c the blank 
character attribute. 

The value for c must be representable as an unsigned character, or EOF. 

In the "POSIX" and "C" locales, the tab and space characters have the blank 
attribute. 


Return Value i sbl ank returns a nonzero value if the integer c has the blank attribute; 0 if it does 
not. 

This example tests if c is a blank type. 

linclude <ctype.h> 
linclude <locale.h> 
linclude <stdio.h> 

void check(char c) { 

if ((' ' != c) && (isprint(c))) 
printf(" %c is ", c); 
else 

printf("x%02x is ", c); 
if (!isblank(c)) 
printf("not "); 

puts("a blank type character"); 
return; 



int main(void) 

{ 

printf("In LC_CTYPE category of locale name \"%s\":\n", 
setlocale(LC_CTYPE, NULL)); 
check('a'); 
check(' '); 
check(OxOO); 
check('\n'); 
check('\t'); 

return 0; 

/**************************************************************************** 

The output should be similar to : 

In LC_CTYPE category of locale name "C": 

a is not a blank type character 
x20 is a blank type character 
xOO is not a blank type character 
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x0a is not a blank type character 
x09 is a blank type character 

****************************************************************************/ 


• “i sal num to isxdigi t — Test Integer Value” on page 347 

• “isascii —Test Integer Values” on page 350 

• “_i scsym - _i scsymf — Test Integer” on page 356 

• “i swal num to i swxdigi t — Test Wide Integer Value” on page 360 

• “i swbl ank — Test for Wide Blank Character Classification” on page 363 

• “setl ocal e — Set Locale” on page 530 

• “<ctype.h>” on page 802 


Chapter 3. Library Functions 355 




iscsym - _iscsymf 


_i scsym - _i scsymf — Test Integer 

Format #include <ctype.h> 

int _iscsym(int c); 
int _iscsymf(int c); 

Language Level: Extension 

These macros test if an integer is within a particular ASCII set. The macros assume 
that the system uses the ASCII character set. 

_i scsym tests if a character is alphabetic, a digit, or an underscore (_). _i scsymf 
tests is a character is alphabetic or an underscore. 


Return Value _i scsym and _i scsymf return a nonzero value if the integer is within the ASCII set 
for which it tests, and 0 if it is not. 



This example uses _i scsym and _i scsymf to test the characters a, _, and 1. If the 
character falls within the ASCII set tested for, the macro returns TRUE. Otherwise, it 
returns FALSE. 

#include <stdio.h> 

#include <ctype.h> 


int main(void) 

{ 

int ch[3] = { 'a'1 1 }; 

i nt i; 


for (i =0; i <3; i++) { 

printf("_iscsym('%c') returns %s\n", ch[i], _iscsym(ch[i])?"TRUE":"FALSE"); 
printf("_iscsymf('%c') returns %s\n\n", ch[i], _iscsymf(ch[i])?"TRUE": 
"FALSE"); 


return 0; 

/•k-k-klt-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-kle-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-kle-k-klck-klck-k-k-k-k-k-k-k-k-k-k-k 

The output should be: 

_iscsym('a') returns TRUE 
_iscsymf('a') returns TRUE 

_iscsym( 1 _ 1 ) returns TRUE 
_iscsymf) returns TRUE 

_iscsym( 1 1 1 ) returns TRUE 
_iscsymf( 1 1') returns FALSE 

■k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1< , k'kic-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k/ 

} 
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• “i sal niim to isxdigi t — Test Integer Value” on page 347 

• “isascii —Test Integer Values” on page 350 

• “i sbl ank — Test for Blank Character Classification” on page 354 

• “i swal num to i swxdi gi t — Test Wide Integer Value” on page 360 

• “i swbl ank — Test for Wide Blank Character Classification” on page 363 

• “tolower - toupper — Convert Character Case” on page 676 

• “_toascii - _tolower - _toupper — Convert Character” on page 673 

• “<ctype.h>” on page 802 
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ismccol1 el 

Format 

Description 


Return Value 



- Identify Multi-Character Collating Element 

linclude <collate.h> 

int ismccol 1 el(col 1 el_t c); 

Language Level: Extension 

i smccol 1 el determines whether the col 1 el_t value represents a multicharacter 
collating element. 

A collating element is a glyph, usually a character, that has a value that defines its 
order in a collating sequence. A multicharacter collating element is a sequence of 
two or more characters that are to be collated as one entity. 

Note: Ifc is greater than 255 and is not a multicharacter collating element, as 
determined by the LC_COLLATE category of the current locale, it is a multibyte 
character, c is the wide character representation for the multibyte character. 

ismccollel returns: 

1 if c represents a multi-character collating element. 

0 if c represents a single-character collating element. 

-1 if c is out of range or otherwise invalid. 

This example prints all the collating elements in the collating sequence by using the 
i smccol 1 el function to determine if the collating element is a multicharacter 
collating element. 

#include <stdio.h> 

#include <locale.h> 

#include <col1ate.h> 

#include <wchar.h> 

int main(void) 

{ 

col 1 el_t *rp; 
int i; 

setlocale(LC_ALL, LC_C_FRANCE); 
i = col 1order(&rp); 
for (; i >0; rp++, i--) { 
i f (i smccol1 el(*rp)) 

printf(" 1 %s' ", col 1tostr(*rp)); 
else if (iswprint(*rp)) 

printf("'%1c' ", *rp); 
else 

printf(" 1 %x 1 ", *rp); 


return 0; 

The output should be similar to : 
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■ 1 .. 

'Les 1 'Le 

.q, ,j, . 2 < 

■g' . A . . B . 

1 P' ' Q' 1 R 1 


'#' '$' '%' 
'La 1 'L" 
7' 

■ 3 ' ' 4 ' ' 5 ' 
'C' 'D' 1 E 1 
■S' 'T' 'U 1 


'&' 1 (' " 1 
'du 1 'des 

' 6 ' 1 7 1 ' 8 ' 
' F ' 1 G' ' H 1 
■v 'W' 'X' 


)' 

' de 1 'd" 
9 ' 

I' 'J 1 'K 1 
V 'V '[' 


'Du 1 'Des 
'les ' ' 1 e 

.<. i = i i>i 

' L' ' M' ' N' 

'V ']' '"' 


De ' 'D" 
la ' '1 " 


O' 


****************************************************************************/ 


• “ccl ass — Return Characters in Character Class” on page 82 

• “col 1 equi v — Return List of Equivalent Collating Elements” on page 101 

• “col 1 order — Return List of Collating Elements” on page 103 

• “col 1 range — Calculate Range of Collating Elements” on page 105 

• “col 1 tostr — Return String for Collating Element” on page 107 

• “getmccol 1 — Get Next Collating Element from String” on page 306 

• “getwmccol 1 — Get Next Collating Element from Wide Suing” on page 319 

• “maxcol 1 — Return Maximum Collating Element” on page 409 

• “strtocol 1 — Return Collating Element for Suing” on page 619 

• “<collate.h>” on page 802 
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i swal num to 

Format 


Description 


i swxdigi t — Test Wide Integer Value 


linclude <wctype.h> 

int i swal num(wint_t wc)-, 
int iswalpha(wint_t wc)-, 
int iswcntrl (wint_t wc)-, 
int iswdigit(wint_t wc)-, 
int iswgraph(wint_t wc); 
int iswlower(wint_t wc); 
int iswprint(wint_t wc); 
int iswpunct(wint_t wc); 
int iswspace(wint_t wc); 
int iswupper(wint_t wc); 
int iswxdigit(wint_t wc); 


/* test for: */ 

/* wide alphanumeric character */ 

/* wide alphabetic character */ 

/* wide control character */ 

/* wide decimal digit */ 

/* wide printable character, excluding space */ 

/* wide lowercase character */ 

/* wide printable character, including space */ 

/* wide punctuation character, excluding space */ 
/* wide whitespace character */ 

/* wide uppercase character */ 

/* wide hexadecimal digit */ 


Language Level: ANSI 93, POSIX, XPG4 


These functions test a given wide integer value wc to determine whether it has a 
certain property as defined by the LC_CTYPE category of your current locale. The 
value of wc must be representable as a wchar_t, or WEOF. 


The functions test for the following: 


iswalnum 

Wide alphanumeric character (upper- or lowercase letter, or decimal 
digit), as defined in the locale source file in the alnum class of the 
LC_CTYPE category of the current locale. 

iswalpha 

Wide alphabetic character, as defined in the locale source file in the 
alpha class of the LC_CTYPE category of the current locale. 

iswcntrl 

Wide control character, as defined in the locale source file in the cntrl 
class of the LC_CTYPE category of the current locale. 

iswdigit 

Wide decimal digit (0 through 9), as defined in the locale source file in 
the digit class of the LC_CTYPE category of the current locale. 

iswgraph 

Wide printable character, excluding the space character, as defined in 
the locale source file in the graph class of the LC_CTYPE category of 
the current locale. 

iswlower 

Wide lowercase letter, as defined in the locale source file in the 1 ower 
class of the LC_CTYPE category of the current locale. 

iswprint 

Wide printable character, including the space character, as defined in 
the locale source file in the pri nt class of the LC_CTYPE category of 
the current locale. 
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Return Value 



i swpunct Wide non-alphanumeric printable character, excluding the space 

character, as defined in the locale source file in the punct class of the 
LC_CTYPE category of the current locale. 

i swspace Wide white-space character, as defined in the locale source file in the 
space class of the LC_CTYPE category of the current locale. 

i swupper Wide uppercase letter, as defined in the locale source file in the upper 
class of the LC_CTYPE category of the current locale. 


iswxdigit Wide hexadecimal digit (0 through 9, a through f, or A through F), as 
defined in the locale source file in the xdigit class of the LC_CTYPE 
category of the current locale. 


You can redefine any character class in the LC_CTYPE category of the current 
locale. For more information, see “Introduction to Locales” in the Programming 
Guide. 


These functions return a nonzero value if the wide integer satisfies the test value; 0 
if it does not. 

This example analyzes all characters between 0x0 and OxFF. The output of this 
example is a 256-line table showing the characters from 0 to 255, indicating whether 
they have the properties tested for. 

#include <1ocale.h> 
lire!ude <stdio.h> 

#inc1ude <wctype.h> 

#define UPPER_LIMIT 0xFF 

int main(void) 

{ 

wint_t wc; 

setlocale(LC_ALL, LC_C_USA); 


(wc = 0; wc <= UPPERLIMIT; 
printf("%#4x ", wc) ; 

WC++) 


printf("%c", 

iswprint(wc) ? 

wc 

' '); 

printf("%s". 

iswalnum(wc) ? 

" AN" 

n ii j 

printf("%s", 

iswalpha(wc) ? 

" A " 

■ ") 

printf("%s", 

iswcntrl(wc) ? 

" C " 

■ ") 
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printf("%s", 

iswdigit(wc) 

? 

" D " 


") 

printf("%s", 

iswgraph(wc) 

? 

" G " 


■) 

printf(“%s". 

iswlower(wc) 

? 



") 

printf("%s". 

iswpunct(wc) 

? 

" PU" 


") 

printf ("%s\ 

iswspace(wc) 

? 

" S " 


") 

printf("%s". 

iswprint(wc) 

? 

" PR" 


") 

printf(“%s". 

iswupper(wc) 

? 

" U " 


") 

printf("%s". 

iswxdigit(wc) 

? 

" H " 


") 


putchar( 1 \n 1 ); 

} 

return 0; 

/******************■******************************'******'********'***'*'**'***'*'**'** 


The output 

should 

be 

simi 1 ar 

to : 


0x20 



S 

PR 


0x21 ! 


G 

PU 

PR 


0x22 " 


G 

PU 

PR 


0x23 # 


G 

PU 

PR 


0x24 $ 


G 

PU 

PR 


0x25 % 


G 

PU 

PR 


0x26 & 


G 

PU 

PR 


0x27 ' 


G 

PU 

PR 


0x28 ( 


G 

PU 

PR 


0x29 ) 


G 

PU 

PR 


0x2a * 


G 

PU 

PR 


0x2b + 


G 

PU 

PR 


0x2c , 


G 

PU 

PR 


0x2d - 


G 

PU 

PR 


0x2e . 


G 

PU 

PR 


0x2f / 


G 

PU 

PR 


0x30 0 AN 

D 

G 


PR 

H 

0x31 1 AN 

D 

G 


PR 

H 

0x32 2 AN 

D 

G 


PR 

H 

0x33 3 AN 

D 

G 


PR 

H 

0x34 4 AN 

D 

G 


PR 

H 

0x35 5 AN 

D 

G 


PR 

H 

0x36 6 AN 

D 

G 


PR 

H 

0x37 7 AN 

D 

G 


PR 

H 

0x38 8 AN 

D 

G 


PR 

H 

0x39 9 AN 

D 

G 


PR 

H 


i<1e*1<1('ki<*-ki<‘k-ki<‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-ki<‘k-ki<‘k-k-k1c-k-k-k-ki<‘k-ki<‘k-ki<‘k-k-k‘k-ki<‘k-ki<‘k-k-k-k-k-k‘k-ki<‘k'ki<‘k-ki</ 


• “i sal num to i sxdigi t — Test Integer Value” on page 347 

• “isascii —Test Integer Values” on page 350 

• “i sbl ank — Test for Blank Character Classification” on page 354 

• “_i scsym - _i scsymf — Test Integer” on page 356 

• “i swbl ank — Test for Wide Blank Character Classification” on page 363 

• “i swctype — Test for Character Property” on page 365 

• “<wctype.h>” on page 823 
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iswblank — 

Format 

Description 


Return Value 



Test for Wide Blank Character Classification 

linclude <wctype.h> 
int iswblank(wint_t wc ); 

Language Level: Extension 

i swbl ank tests whether the current LC_CTYPE locale category assigns the the blank 
character attribute to the wide character wc. 

The value for wc must be representable as a wchar_t, or WEOF. 

The behavior of i swbl ank is affected by the LC_CTYPE category of the current 
locale. 

In the "POSIX" and "C" locales, the tab and space characters have the blank 
attribute. 


i swbl ank returns a nonzero value if wc has the blank attribute; 0 if it does not. 

This example tests whether wc is a blank type. 

#include <stdio.h> 

#include <wctype.h> 

#include <wchar.h> 

#include <1ocale.h> 

void check(wchar_t wc) { 

if ((' 1 != wc) && (iswprint(wc))) 
printf(" %1c is ", wc); 

el se 

printf("x%02x is ", wc); 
if (!iswblank(wc)) 
printf("not "); 

puts("a blank type character"); 
return; 


int main(void) 

{ 

printf("In LC_CTYPE category of locale name \"%s\":\n", 
setlocale(LC_CTYPE, NULL)); 
check(L'a'); 
check(L' '); 
check(0x00); 
check(L'\n'); 
check(L'\t 1 ); 
return 0; 

/**************************************************************************** 
The output should be similar to : 
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In LC_CTYPE category of locale name "C": 

a is not a blank type character 
x20 is a blank type character 
x00 is not a blank type character 
xOa is not a blank type character 
x09 is a blank type character 

} 



“i sal num to i sxdi gi t — Test Integer Value” on page 347 

“i sasci i — Test Integer Values” on page 350 

“i sbl ank — Test for Blank Character Classification” on page 354 

“_i scsym - _i scsymf — Test Integer” on page 356 

“iswalnum to iswxdigit — Test Wide Integer Value” on page 360 

“i swctype — Test for Character Property” on page 365 

“<wctype.h>” on page 823 
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iswctype — 

Format 

Description 


Return Value 


Test for Character Property 

linclude <wctype.h> 

int iswctype(wint_t wc, wctype_t wc_prop); 


Language Level: ANSI 93, XPG4 

i swctype determines whether the wide character wc has the property wc_prop. It is 
similar in function to the i swal num through i sxdigi t functions, but with i swctype 
you can specify the property to check for, or check for a property other than the 
standard ones. 


You must obtain the wc_prop value from a call to wctype. If you do not, or if the 
LC_CTYPE category of the locale was modified after you called wctype, the 
behavior of i swctype is undefined. 

The value of wc must be representable as an unsigned wchar_t, or WEOF. 

The following strings correspond to the standard (basic) character classes or 
properties: 

"alnum" "cntrl" "lower" "space" 

"alpha" "digit" "print" "upper" 

"blank" "graph" "punct" "xdigit" 


The following shows calls to wctype and indicates the equivalent i sw* function: 


iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc, 
iswctype(wc. 


wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 
wctype( 


"alnum")) 
"alpha")) 
"blank")) 
"cntrl")) 
"digit")) 
"graph")) 
"lower")) 
"print")) 
"punct")) 
"space")) 
"upper")) 
"xdigit")) 


/* 

iswalnum(wc) 

*/ 

/* 

iswalpha(wc) 

*/ 

/* 

iswblank(wc) 

*/ 

/* 

iswcntrl(wc) 

*/ 

/* 

iswdigit(wc) 

*/ 

/* 

iswgraph(wc) 

*/ 

/* 

iswlower(wc) 

*/ 

/* 

iswprint(wc) 

*/ 

/* 

iswpunct(wc) 

*/ 

/* 

iswspace(wc) 

*/ 

/* 

iswupper(wc) 

*/ 


/* i 


swxdigit(wc); */ 


i swctype returns a nonzero value if the wide character has the property tested for. 
If the value for wc or wc_prop is not valid, the behavior is undefined. 
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This example analyzes all characters between 0x0 and OxFF. The output of this 
example is a 256-line table showing the characters from 0 to 255, indicating whether 
they have the properties tested for. 


#include <locale.h> 
#include <stdio.h> 
#include <wctype.h> 


#define UPPER_LIMIT OxFF 

int main(void) 

{ 

wint_t wc; 


setlocale(LC_ALL, LC_C_USA); 

for (wc = 0; wc <= UPPER_LIMIT; wc++) { 


printf("%#4x 

". wc); 





printf("%c", 

iswctype(wc. 

wctype("print")) 

? 

wc 

1 '); 

printf("%s", 

iswctype(wc. 

wctype("alnum")) 

? 

" AN" 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("alpha")) 

? 

" A " 

" ") 

printf("%s", 

iswctype(wc. 

wctype("blank")) 

? 

" B " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("cntrl")) 

? 

" C " 

‘ ") 

printf("%s", 

iswctype(wc. 

wctype("digit")) 

? 

" D " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("graph")) 

? 

" G " 

‘ ") 

printf("%s", 

iswctype(wc. 

wctype("lower")) 

? 


■ ") 

printf("%s", 

iswctype(wc. 

wctype("punct")) 

? 

" PU" 

‘ ") 

printf("%s", 

iswctype(wc. 

wctype("space")) 

? 

" S " 

" ") 

printf("%s", 

iswctype(wc. 

wctype("print")) 

? 

" PR” 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("upper")) 

? 

" U " 

" ") 

printf("%s", 
putchar('\n 1 

iswctype(wc, 

; 

wctype("xdigit")) 

? 

" H " 

■ ") 


return 0; 

/**************************************************************************** 

The output should be similar to : 


Oxle C 

Oxlf C 


0x20 

B 


S 

PR 

0x21 ! 


G 

PU 

PR 

0x22 " 


G 

PU 

PR 

0x23 # 


G 

PU 

PR 

0x24 $ 


G 

PU 

PR 

0x25 % 


G 

PU 

PR 
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0x30 0 AN 

D 

G 

PR 

H 

0x31 1 AN 

D 

G 

PR 

H 

0x32 2 AN 

D 

G 

PR 

H 

0x33 3 AN 

D 

G 

PR 

H 

0x34 4 AN 

D 

G 

PR 

H 

0x35 5 AN 

D 

G 

PR 

H 

0x43 C AN A 


G 

PR U 

H 

0x44 D AN A 


G 

PR U 

H 

0x45 E AN A 


G 

PR U 

H 

0x46 F AN A 


G 

PR U 

H 

0x47 G AN A 


G 

PR U 



****************************************************************************/ 


• “i sal num to isxdigi t — Test Integer Value” on page 347 

• “isascii —Test Integer Values” on page 350 

• “i sbl ank — Test for Blank Character Classification” on page 354 

• “_i scsym - _i scsymf — Test Integer” on page 356 

• “i swal num to i swxdigi t — Test Wide Integer Value” on page 360 

• “i swbl ank — Test for Wide Blank Character Classification” on page 363 

• “i swal num to i swxdi gi t — Test Wide Integer Value” on page 360 

• “wctype — Get Handle for Character Property Classification” on page 795 

• “<wctype.h>” on page 823 
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itoa — Convert Integer to String 

Format linclude <stdlib.h> 

char *_itoa(int value, char * string, int radix)-. 

Description Language Level: Extension 

_i toa converts the digits of the given value to a character string that ends with a 
null character and stores the result in string. The radix argument specifies the base 
of value; it must be in the range 2 to 36. If radix equals 10 and value is negative, 
the first character of the stored string is the minus sign (-). 

Note: The space reserved for string must be large enough to hold the returned 
string. The function can return up to 33 bytes including the null character (\0). 

Return Value _itoa returns a pointer to string. There is no error return value. 

This example converts the integer value -255 to a decimal, a binary, and a hex 
number, storing its character representation in the array buffer. 

linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

char buffer[35]; 
char *p; 

p = _itoa(-255, buffer, 10); 

printf("The result of _itoa(-255) with radix of 10 is %s\n", p); 
p = _itoa(-255, buffer, 2); 

printf("The result of _itoa(-255) with radix of 2\n is %s\n", p); 
p = _itoa(-255, buffer, 16); 

printf("The result of _itoa(-255) with radix of 16 is %s\n", p); 
return 0; 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

The output should be: 

The result of _itoa(-255) with radix of 10 is -255 
The result of _itoa(-255) with radix of 2 
is 11111111111111111111111100000001 
The result of _itoa(-255) with radix of 16 is ffffffOl 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

} 

• “_ecvt — Convert Floating-Point to Character” on page 192 

• “_fcvt — Convert Floating-Point to String” on page 217 

• “_gcvt — Convert Floating-Point to String” on page 294 

• “_1 toa — Convert Long Integer to String” on page 395 

• “_ul toa — Convert Unsigned Long Integer to String” on page 716 

• “<stdlib.h>” on page 816 
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kbhit — Test for Keystroke 

Format include <conio.h> 

int _kbhit(void); 


Description Language Level: Extension 

_kbhit tests if a key has been pressed on the keyboard. If the result is nonzero, a 
keystroke is waiting in the buffer. You can read in the keystroke using the _getch or 
_getche function. If you call _getch or _getche without first calling _kbhit, the 
program waits for a key to be pressed. 


Return Value _kbhit returns a nonzero value if a key has been pressed. Otherwise, it returns 0. 



This example uses _kbhi t to test for the pressing of a key on the keyboard and to 
print a statement with the test result. 

#include <conio.h> 

#include <stdio.h> 


int main(void) 

{ 

int ch; 

printf("Type in some letters.\n"); 

printf("If you type in an 'x 1 , the program ends.\n"); 

for (; ; ) { 

while (0==_kbhit()){ 

/* Processing without waiting for a key to be pressed */ 

} 


ch = _getch(); 

printf("You have pressed the 1 %c' key.\n",ch); 

if ('x 1 == ch) 
break; 

} 

return 0; 

/**************************************************************************** 
The output should be similar to; 

Type in some letters. 

If you type in an 'x', the program ends. 

You have pressed the 'f' key. 

You have pressed the 'e' key. 

You have pressed the '1' key. 

You have pressed the 1 i 1 key. 

You have pressed the 'x' key. 

****************************************************************************/ 

} 



“_getch - _getche — Read Character from Keyboard” on page 298 
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• “<conio.h>” on page 802 


370 VisualAge C++ C Library Reference 



labs 


labs — Calculate Absolute Value of Long Integer 

Format linclude <stdlib.h> 

long int labs (long int n); 

Description Language Level: ANSI, SAA, XPG4 

labs produces the absolute value of its long integer argument n. The result may be 
undefined when the argument is equal to L0NG_MIN. the smallest available long integer 
(-2 147 483 647). The value L0NG_MIN is defined in the <1 imits.h> include file. 

Return Value labs returns the absolute value of n. There is no error return value. 

This example computes y as the absolute value of the long integer -41567. 

#inc1ude <stdlib.h> 

int main(void) 

{ 

long x,y; 

x = -41567L; 
y - labs(x); 

printf("The absolute value of %ld is %ld\n", x, y); 
return 0; 

/**************************************************************************** 

The output should be: 

The absolute value of -41567 is 41567 

****************************************************************************/ 

i 

• “abs — Calculate Integer Absolute Value” on page 48 

• “_cabs — Calculate Absolute Value of Complex Number” on page 78 

• “fabs — Calculate Floating-Point Absolute Value” on page 207 

• “<limits.h>” on page 806 
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ldexp — Multiply by a Power of Two 

Format linclude <math.h> 

double ldexp(double x, int exp); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

ldexp calculates the value of x * (2 exp). 

Return Value ldexp returns the value of x*(2 ex P). If an overflow results, the function returns 

+HUGE_VAL for a large result or -HUGE_VAL for a small result, and sets errno to ERANGE. 

This example computes / as 1.5 times 2 to the fifth power (1.5*2 5 ): 
linclude <math.h> 

int main(void) 

{ 

double x,y; 
int p; 

x = 1.5; 

P = 5; 

y = ldexp(x, p); 

printf("%lf times 2 to the power of %d is %lf\n", x, p, y); 
return 0; 

/*********************************************■*****************■******'***'***'** 

The output should be: 

1.500000 times 2 to the power of 5 is 48.000000 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k‘k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k j 

} 

• “exp — Calculate Exponential Function” on page 206 

• “frexp — Separate Floating-Point Value” on page 270 

• “modf — Separate Floating-Point Value” on page 440 

• “<math.h>” on page 811 
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ldiv — Perform Long Division 

Format linclude <stdlib.h> 

ldiv_t ldiv(long int numerator, long int denominator); 

Description Language Level: ANSI, SAA, XPG4 

ldiv calculates the quotient and remainder of the division of numerator by 
denominator. 

Return Value ldiv returns a structure of type ldiv_t, containing both the quotient (long int quot) 
and the remainder (long int rem). If the value cannot be represented, the return 
value is undefined. If denominator is 0, an exception is raised. 

This example uses ldiv to calculate the quotients and remainders for a set of two 
dividends and two divisors. 

#inc1ude <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

long int num[2] = { 45,-45 }; 

long int den[2] = { 7,-7 }; 

1div_t ans; /* ldiv_t is a struct type containing two long ints: 

'quot' stores quotient; 'rem' stores remainder */ 

short i,j; 

printf("Results of long division:\n"); 
for (i = 0; i < 2; i++) 
for (j = 0; j < 2; j++) { 
ans = ldiv(num[i], den [j]); 

printf ("Dividend: %61d Divisor: %61d", num[i], den [j]); 
printf(" Quotient: %61d Remainder: %61d\n", ans.quot, ans.rem); 

} 

return 0; 

/**************************************************************************** 

The output should be: 

Results of long division: 

Dividend: 45 Divisor: 7 Quotient: 6 Remainder: 3 

Dividend: 45 Divisor: -7 Quotient: -6 Remainder: 3 

Dividend: -45 Divisor: 7 Quotient: -6 Remainder: -3 

Dividend: -45 Divisor: -7 Quotient: 6 Remainder: -3 

****************************************************************************/ 

} 

• “div — Calculate Quotient and Remainder” on page 169 

• “<stdlib.h>” on page 816 
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1 find - lsearch — Find Key in Array 

Format linclude <search.h> 

char *1 find(char *search_key, char *base, 

unsigned int *num, unsigned int *width, 
int {*compare) (const void *key, const void *element))\ 
char *1search(char *search_key, char *base, 

unsigned int *num, unsigned int *width, 

int [^compare) (const void *key, const void *element)); 

Description Language Level: XPG4, Extension 

1 find and 1 search perform a linear search for the value search_key in an array of 
num elements, each of width bytes in size. Unlike bsearch, lsearch and lfind do 
not require that you sort the array first. The argument base points to the base of the 
array to be searched. 

If 1 search does not find the search_key , it adds the search_key to the end of the 
array and increments num by one. If 1 f i nd does not find the search_key, it does not 
add the search_key to the array. 

The compare argument is a pointer to a function you must supply that takes a pointer 
to the key argument and to an array element , in that order. Both 1 fi nd and 
1 search call this function one or more times during the search. The function must 
compare the key and the element and return one of the following values: 

Value Meaning 

Nonzero key and element are different. 

0 key and element are identical. 

Note: In earlier releases of C Set ++, lfind and lsearch began with an underscore 
(_1 find and _1 search). Because they are defined by the X/Open standard, the 
underscore has been removed. For compatibility, VisualAge C++ will map _l fi nd 
and _1 search to 1 fi nd and 1 search for you. 


Return Value If search_key is found, both 1 search and 1 f i nd return a pointer to that element of 
the array to which base points. If search_key is not found, 1 search returns a 
pointer to a newly added item at the end of the array, while 1 fi nd returns NULL. 



This example uses 1 f i nd to search for the keyword PATH in the command-line 
arguments. 
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#include <search.h> 

#include <string.h> 

#include <stdio.h> 

Idefine CNT 2 

*/ 
*/ 
*/ 

int _Optlink compare(const void *argl,const void *arg2) 

{ 

return (strncmp(*(char **)argl, *(char **)arg2, strlen(*(char **)argl))); 

} 


/* Note: Library always calls functions internally with _0ptlink 
/* linkage convention. Ensure that compare() is always 

/* _0ptlink. 


int main(void) 

{ 

char **result; 
char *key = "PATH"; 
unsigned int num = CNT; 
char *string[CNT] = { 

"PATH = d:\\david\\matthew\\heather\\ed\\simon","LIB = PATHWabc" }; 

/* The following statement finds the argument that starts with "PATH" */ 

if ((result = (char **)1find((char *)&key, (char *)string, &num, 
sizeof(char *), compare)) != NULL) 
printf("%s found\n", *result); 
el se 

printf("PATH not found \n"); 
return 0; 

/**************************************************************************** 
The output should be: 

PATH = d:\david\matthew\heather\ed\simon found 
****************************************************************************/ 

} 


• “bsearch — Search Arrays” on page 76 

• “qsort — Sort Array” on page 478 

• “<search.h>” on page 813 
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_1oadmod — 

Format 

Description 


Return Value 



Load DLL 

#include <stdlib.h> 

int _1oadmod(char *module_name, unsigned long *module_handle); 

Language Level: Extension 

_1 oadmod loads a dynamic link library (DLL) for the calling process. The 
module_name is the name of the DLL to be loaded, and the module_handle is the file 
handle associated with the DLL. 

Note: _1 oadmod and _freemod perform exactly the same function as the OS/2 APIs 
DosLoadModule and DosFreeModule. They are provided for compatibility with 
earlier VisualAge C++ releases only, and will not be supported in future 
versions. Use DosLoadModule and DosFreeModule instead. For more details on 
these APIs, see the Control Program Guide and Reference. 

If the operation is successful, _1 oadmod returns the handle of the loaded DLL to the 
calling process. The process can use this handle with the OS/2 API DosQueryProcAddr 
to get the address of the required function from within the DLL. Once the reference 
is established, the calling process can then call the specific function. 

_1 oadmod returns 0 if the DLL was successfully loaded. If unsuccessful, _1 oadmod 
returns -1, and sets errno to one of the following values: 

Value Meaning 

EMODNAME The specified module_name is not valid. 

EOS2ERR A system error occurred. Check _doserrno for the specific OS/2 
error code. 

In this example, _1 oadmod loads the DLL mark and gets the address of the function 
PLUS within the DLL. It then calls that function, which adds two integers passed to it. 
The types PFN and APIRET are required to use the OS/2 DosQueryProcAddr API, and 
are defined by including the <os2. h> header file. 

Note: To run this program, you must first create mark.dl 1. Copy the code for the 
PLUS function into a file called mark.c, and the code for the ,DEF file into mark.def. 
Eliminate the comments from these two files. Compile with the command: 

icc /Ge- mark.c mark.def 

You can then run the example. 
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Idefine INCL_D0S 
#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

/* This is the code for MARK.DEF 

LIBRARY MARK 

PROTMODE 

EXPORTS PLUS */ 

/* This is the code for PLUS function in the DLL 
Ipragma linkage( PLUS, system ) 
int PLUS( int a , int b) 


return a + b; 

} */ 

int main(void) 

{ 

int x = 4,y = 7; 
unsigned long handle; 

char *modname = "MARK"; /* DLL name */ 

char *fname = "PLUS"; /* function name */ 

PFN faddr; /* pointer to function */ 

APIRET rc; /* return code from DosQueryProcAddr */ 


/* dynamically load the 'mark' DLL */ 

if (_loadmod(modname, &handle)) { 

printf("Error loading module %s\n", modname); 
return EXIT_FAILURE; 

} 


/* get function address from DLL */ 

rc = DosQueryProcAddr(handle, 0, fname, &faddr); 
if (0 == rc) { 

printf("Cal 1ing the function from the %s DLL to add %d and %d\n", modname, 
x, y); 

printf("The result of the function call is %d\n", faddr(x, y)); 

} 

el se { 

printf("Error locating address of function %s\n", fname); 

_freemod(handle); 
return EXIT_FAILURE; 

} 

if (_freemod(handle)) { 

printf("Error in freeing the %s DLL module\n", modname); 
return EXIT_FAILURE; 
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printf("Reference to the %s DLL module has been freed\n", modname); 
return 0; 

/**************************************************************************** 

The output should be: 

Calling the function from the MARK DLL to add 4 and 7 
The result of the function call is 11 
Reference to the MARK DLL module has been freed 
****************************************************************************/ 

} 



“_freemod — Free User DLL” on page 265 
“<stdlib.h>” on page 816 
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1ocaldtconv 

Format 

Description 

Return Value 



— Return Date and Time Formatting Convention 

linclude <locale.h> 

struct dtconv *localdtconv(void); 

Language Level: Extension 

localdtconv determines the date and time formatting conventions of the current 
locale and places the information in a structure of type struct dtconv. The dtconv 
structure is described in detail on page 809. 

Subsequent calls to localdtconv or to setlocale with LC_ALL or LC_TIME can 
overwrite the structure. 


localdtconv returns the address of the dtconv structure. 

This example sets the Spanish locale, calls localdtconv to determine how date and 
time are formatted, and prints the fields from the resulting structure. 

#include <stdio.h> 

#include <1ocale.h> 

#include <stdlib.h> 

int main(void) 

{ 

struct dtconv *p; 
int i; 

if (NULL == setlocale(LC_ALL, LC_C_SPAIN)) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

el se { 

p = local dtconv (); 

printf("SPAIN date/time convention.\n"); 
printf(" Abbreviated month names:"); 
for (i = 0; i < 12; ++i) 

printf(" %s", p->abbrev_month_names[i]); 
printf("\n Full month names:"); 
for (i = 0; i < 12; ++i) 

printf(" %s", p->month_names[i]); 
printf("\n Abbreviated day names:"); 
for (i =0; i <7; ++i) 

printf(" %s", p->abbrev_day_names[i]); 
printf("\n Full day names:"); 
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for (i = 0; i < 7; ++i) 

printf(" %s", p->day_names[i]); 
printf("\n Date and time format: %s\n", 
printf(" Date format: %s\n", 
printf(" Time format: %s\n", 
printf(" AM string: %s\n", 
printf(" PM string: %s\n", 
printf(" Long date format: %s\n". 


p->date_time_format); 
p->date_format); 
p->time_format); 
p->am_string); 
p->pm_string); 
p->time_format_ampm); 


return 0; 


/•k*1<‘k-k-k‘k-k1<‘k-k-k‘k-k1<‘k'k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k1c-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k-k-k-k‘k-k-k‘k-k-k-k 

The output should be similar to : 

SPAIN date/time convention. 

Abbreviated month names: ENE FEB MAR ABR MAY JUN JUL AGO SEP OCT NOV DIC 
Full month names: Enero Febrero Marzo Abril Mayo Junio Julio Agosto 
Septiembre Octubre Noviembre Diciembre 
Abbreviated day names: DOM LUN MAR MIE JUE VIE SAB 
Full day names: Domingo Lunes Martes Miercoles Jueves Viernes Sabado 
Date and time format: %d %B %Y %H:%M:%S 
Date format: %d/%m/%y 
Time format: %H:%M:%S 
AM string: 

PM string: 

Long date format: %H:%M:%S %p 

****************************************************************************/ 

} 



“localeconv — Retrieve Information from the Environment'’ on page 381 

“localtime — Convert Time” on page 385 

“setlocale — Set Locale” on page 530 

“strftime — Convert to Formatted Time” on page 586 

“strptime — Convert to Formatted Date and Time” on page 605 

“wcsftime — Convert to Formatted Date and Time” on page 760 

“<locale.h>” on page 806 
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localeconv — Retrieve Information from the Environment 

Format linclude <locale.h> 

struct lconv *1ocaleconv (void); 


Description Language Level: ANSI, SAA, XPG4 

localeconv retrieves information about the environment for the current locale and 
places the information in a structure of type struct lconv. Subsequent calls to 
localeconv, or to setlocale with the argument LC_ALL, LC_MONETARY, or 
LC_NUMERIC, can overwrite the structure. 


The structure contains the members listed below. Defaults shown are for the "C" 
locale. Pointers to strings with a value of "" indicate that the value is not available 
in this locale or is of zero length. Character types with a value of UCHAR_MAX 
indicate that the value is not available in this locale. 


Element 

char *decimal_point 
char *thousands_sep 


char *grouping 


char *int_curr_symbol 


char *currency_symbol 
char *mon_decimal_point 

char *mon_thousands_sep 


Purpose of Element Default 

Decimal-point character for formatting 
nonmonetary quantities. 

Character used to separate groups of 1 " 

digits to the left of the decimal-point 
character in formatted nonmonetary 
quantities. 

Size of each group of digits in formatted 1 " 
nonmonetary quantities. The value of 
each character in the string determines 
the number of digits in a group. 

CHAR_MAX indicates that there are no 
further groupings. 0 indicates that the 
previous element is to be used for the 
remainder of the digits. 

International currency symbol. The first 1 " 
three characters contain the alphabetic 
international currency symbol. The 
fourth character (usually a space) 
separates the international currency 
symbol from the monetary quantity. 

Local currency symbol. "" 

Decimal-point character for formatting "." 

monetary quantities. 

Separator for digits in formatted monetary "" 
quantities. 
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Element 

char *mon_grouping 


char *positive_sign 
char *negative_sign 

char int_frac_digits 

char frac_digits 
char p_cs_precedes 

char p_sep_by_space 

char n_cs_precedes 

char n_sep_by_space 

char p_sign_posn 
char n_sign_posn 
char *1eft_parenthesis 

char *right_parenthesis 

char *debit_sign 
char *credit_sign 


Purpose of Element 

Size of each group of digits in formatted 
monetary quantities. The value of each 
character in the string determines the 
number of digits in a group. CHAR_MAX 
indicates that there are no further 
groupings. 0 indicates that the previous 
element is to be used for the remainder of 
the digits. 

Positive sign used in monetary quantities. 
Negative sign used in monetary 
quantities. 

Mumber of displayed digits to the right 
of the decimal place for internationally 
formatted monetary quantities. 

Number of digits to the right of the 
decimal place in monetary quantities. 

1 if the currency_symbol precedes the 
value for a nonnegative formatted 
monetary quantity; 0 if it does not. 

1 if the currency_symbol is separated by a 
space from the value of a nonnegative 
formatted monetary quantity; 0 if it is 
not. 

1 if the currency_symbol precedes the 
value for a negative formatted monetary 
quantity; 0 if it does not. 

1 if the currency_symbol is separated by a 
space from the value of a negative 
formatted monetary quantity; 0 if it is 
not. 

Position of the positive_sign for a 
nonnegative formatted monetary quantity. 
Position of the negati ve_si gn for a 
negative formatted monetary quantity. 
Symbol to appear to the left of a 
negative-valued monetary symbol (such 
as a loss or deficit). 

Symbol to appear to the right of a 
negative-valued monetary symbol (such 
as a loss or deficit). 

String to indicate a non-negative-valued 
formatted monetary quantity. 

String to indicate a negative-valued 
formatted monetary quantity. 


Default 


UCHAR_MAX 

UCHAR_MAX 

UCHAR_MAX 

UCHAR_MAX 

UCHAR_MAX 

UCHAR_MAX 

UCHAR_MAX 

UCHAR_MAX 

"DB" 

"CR" 
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The grouping and mon_grouping members can have the following values: 

Value Meaning 

CHAR_MAX No further grouping is to be performed. 

0 The previous element is to be repeatedly used for the rest of the 

digits. 

other The number of digits that comprise the current group. The next 

element is examined to determine the size of the next group of digits 
before the current group. 

The n_sign_posn and p_sign_posn elements can have the following values: 

Value Meaning 

0 The quantity and currency_symbol are enclosed in parentheses. 

1 The sign precedes the quantity and currency_symbol. 

2 The sign follows the quantity and currency_symbol. 

3 The sign precedes the currency_symbol. 

4 The sign follows the currency_symbol. 

5 Use debit_sign for p_sign_posn or credit_sign for n_sign_posn. 

Return Value localeconv returns a pointer to the lconv structure. 

This example prints out the default decimal point for your locale and then the decimal 
point for the LC_C_FRANCE locale. 

# inc 1ude <stdi o.h> 

#inc1ude <1ocale.h> 

int main(void) 

{ 

struct lconv *mylocale; 
mylocale = localeconv(); 

printf("Default decimal point is a %s\n", mylocale->decimal_point); 

if (NULL != setlocale(LC_ALL, LC_C_FRANCE)) { 
mylocale = localeconv(); 

printf("France's decimal point is a %s\n", mylocale->decimal_point); 

} else { 

printf("setlocale(LC_ALL, LC_C_FRANCE) returned <NULL>\n"); 

} 

return 0; 

/**************************************************************************** 

The output should be similar to : 

Default decimal point is a . 

France's decimal point is a , 

****************************************************************************/ 

} 

• “setl ocal e — Set Locale” on page 530 
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• “<locale.h>” on page 806 
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1ocaltime 

Format 

Description 


Return Value 



Convert Time 

linclude <time.h> 

struct tm *localtime(const time_t *timeval ); 

Language Level: ANSI, SAA, POSIX, XPG4 

localtime breaks down timeval , corrects for the local time zone and Daylight Saving 
Time, if appropriate, and stores the corrected time in a structure of type tm. See 
“gmtime — Convert Time” on page 321 for a description of the fields in a tm 
structure. 

The time value is usually obtained by a call to the time function. 

Notes: 

1. gmtime and local time may use a common, statically allocated buffer for the 
conversion. Each call to one of these functions may alter the result of the 
previous call. 

2. The time and date functions begin at 00:00:00 Coordinated Universal Time, 
January 1, 1970. 

local time returns a pointer to the structure result. If unsuccessful, it returns NULL. 

This example queries the system clock and displays the local time. 

#include <time.h> 

#include <stdio.h> 

int main(void) 

{ 

struct tm *newtime; 
time_t Itime; 

time(&ltime); 

newtime = 1ocaltime(&ltime); 

printf("The date and time is %s", asctime(newtime)); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

The date and time is Wed Oct 31 15:00:00 1995 
****************************************************************************/ 
i 
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“asctime — Convert Time to Character String” on page 55 
“ctime — Convert Time to Character String” on page 129 
“gmtime — Convert Time” on page 321 
“mktime — Convert Local Time” on page 438 
“t i me — Determine Current Time” on page 666 
“<time.h>” on page 819 
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log — Calculate Natural Logarithm 

Format linclude <math.h> 

double log(double x ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

log calculates the natural logarithm (base e) of x. 

Return Value log returns the computed value. If x is negative, log sets errno to EDOM and may 

return the value -HUGE_VAL. If x is zero, log returns the value -HUGE_VAL, and may set 
errno to ERANGE. 

This example calculates the natural logarithm of 1000.0. 

#inc1ude <math.h> 

int main(void) 

{ 

double x = 1000.0,y; 
y = log(x); 

printf("The natural logarithm of %lf is %lf\n", x, y); 
return 0; 

/**************************************************************************** 

The output should be: 

The natural logarithm of 1000.000000 is 6.907755 
****************************************************************************/ 
i 

• “exp — Calculate Exponential Function” on page 206 

• “log 10 — Calculate Base 10 Logarithm” on page 388 

• “pow — Compute Power” on page 460 

• “<math.h>” on page 811 




Chapter 3. Library Functions 387 



loglO 


loglO — Calculate Base 10 Logarithm 

Format linclude <math.h> 

double loglO(double x ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

loglO calculates the base 10 logarithm of x. 

Return Value loglO returns the computed value. If x is negative, loglO sets errno to EDOM and 

may return the value -HUGE_VAL. If x is zero, loglO returns the value -HUGE_VAL, and 

may set errno to ERANGE. 

This example calculates the base 10 logarithm of 1000.0. 
linclude <math.h> 

int main(void) 

{ 

double x = 1000.0,y; 
y = loglO(x); 

printf("The base 10 logarithm of %lf is %lf\n", x, y); 
return 0; 

^•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘kick-k-k-k‘J( 

The output should be: 

The base 10 logarithm of 1000.000000 is 3.000000 

■k'k-k-kle-k-k'k-k-klc-k-kle-k-kle-k-kle-k-k-k-k-kle-k-k'k-k-kle-k-kle-k-k'k-k-k'k-k-k'k-k-k'k'k-k'k-k-klc-k-kle-k-k'k-k-kle-k-k'k-k-kle-k-k'k-k-k-k-k'k/ 

} 

• “exp — Calculate Exponential Function” on page 206 

• “1 og — Calculate Natural Logarithm” on page 387 

• “pow — Compute Power” on page 460 

• “<math.h>” on page 811 
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1ongjmp — 

Format 

Description 


Restore Stack Environment 

linclude <setjmp.h> 

void 1ongjmp(jmp_buf env, int value); 

Language Level: ANSI, SAA, POSIX, XPG4 

longjmp restores a stack environment previously saved in env by setjmp. setjmp and 
longjmp provide a way to perform a nonlocal goto. They are often used in signal 
handlers. 

A call to setjmp causes the current stack environment to be saved in env. A 
subsequent call to longjmp restores the saved environment and returns control to a 
point in the program corresponding to the setjmp call. Execution resumes as if the 
setjmp call had just returned the given value. 

All variables (except register variables) that are accessible to the function that 
receives control contain the values they had when longjmp was called. The values of 
variables that are allocated to registers by the compiler are unpredictable. Because 
any auto variable could be allocated to a register in optimized code, you should 
consider the values of all auto variables to be unpredictable after a longjmp call. 

Note: Ensure that the function that calls setjmp does not return before you call the 
corresponding longjmp function. Calling longjmp after the function calling 
setjmp returns causes unpredictable program behavior. 

The value argument must be nonzero. If you give a zero argument for value , 
longjmp substitutes 1 in its place. 

C++ Considerations: When you call setjmp in a C++ program, ensure that that part 
of the program does not also create C++ objects that need to be destroyed. 
When you call longjmp, objects existing at the time of the setjmp call will 
still exist, but any destructors called after setjmp are not called. For 
example, given the following program: 
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Return Value 



#include <stdio.h> 

#include <setjmp.h> 

class A { 
i nt i; 
public: 

A(int I) {i = I; printf("Constructed at line %d\n", i);} 

~A() {printf("Destroying object constructed at line %d\n",i);} 

}; 

jmp_buf jBuf; 

int main(void) { 

A a 1 (_LINE_); 

if (!setjmp(jBuf)) { 

A a2(_LINE_); 

printf("Press y (and Enter) to longjmp; anything else to return norm 
char c = getchar(); 
if (c == "y 1 ) 

longjmp(jBuf, 1); 

} 

A a3(_LINE_); 

return 0; 


If you return normally, the output would be; 

Constructed at line 13 
Constructed at line 15 

Press y (and Enter) to longjmp; anything else to return normally 
x 

Destroying object constructed at line 15 
Constructed at line 21 
Destroying object constructed at line 21 
Destroying object constructed at line 13 

If you called 1 ongjmp, the output would be: 

Constructed at line 13 
Constructed at line 15 

Press y (and Enter) to longjmp; anything else to return normally 

y 

Constructed at line 21 

Destroying object constructed at line 21 

Destroying object constructed at line 13 

Notice that the object from line 15 is not destroyed. 


longjmp does not use the normal function call and return mechanisms; it has no 
return value. 

This example saves the stack environment at the statement: 
if(setjmp(mark) != 0) ... 
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When the system first performs the if statement, it saves the environment in mark and 
sets the condition to FALSE because setjmp returns a 0 when it saves the environment. 
The program prints the message: 
setjmp has been called 

The subsequent call to function p tests for a local error condition, which can cause it 
to call longjmp. Then, control returns to the original setjmp function using the 
environment saved in mark. This time, the condition is TRUE because -1 is the return 
value from longjmp. The example then performs the statements in the block, prints 
longjmp has been called, calls recover, and leaves the program. 

#include <stdio.h> 

#include <setjmp.h> 

jmp_buf mark; 

int main(void) 

{ 

if (setjmp(mark) != 0) { 

printf("1ongjmp has been called\n"); 
recover(); 
exit(l); 

} 

printf("setjmp has been called\n"); 

P(); 

return 0; 

/**************************************************************************** 

The output should be: 

setjmp has been called 
longjmp has been called 

****************************************************************************/ 

} 


int p(void) 

{ 

int error = 0; 

error = 9; 

if (error != 0) 

longjmp(mark, -1); 


int recover(void) 

{ 

} 


“setjmp — Preserve Environment” on page 528 
goto in the Language Reference 
“<setjmp.h>” on page 813 
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lrotl - lrotr — Rotate Bits of Unsigned Long Value 

Format linclude <stdlib.h> /* also in <builtin.h> */ 

unsigned long _1rotl(unsigned long value, int shift); 
unsigned long _1rotr(unsigned long value, int shift); 

Description Language Level: Extension 

_1 rotl and _1 rotr rotate the unsigned long integer value by shift bits. _1 rotl 
rotates to the left, and _1 rotr to the right. 

Note: Both _1 rotl and _1 rotr are built-in functions, which means they are 
implemented as inline instructions and have no backing code in the library. For this 
reason: 

• You cannot take the address of these functions. 

• You cannot parenthesize a call to either function. (Parentheses specify a call to 
the function's backing code, and these functions have none.) 

Return Value Both functions return the rotated value. There is no error return value. 

This example uses _1 rotl and _1 rotr with different shift values to rotate the long 
integer value 0x01234567. 

linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

unsigned long val = 0X01234567; 

printf("The value of 0x%8.81x rotated 4 bits to the left is 0x%8.81x\n", val, 

_lrotl(val, 4)); 

printf("The value of 0x%8.81x rotated 16 bits to the right is 0x%8.81x\n", 
val, _1rotr(val, 16)); 
return 0; 

/**************************************************************************** 

The output should be: 

The value of 0x01234567 rotated 4 bits to the left is 0x12345670 
The value of 0x01234567 rotated 16 bits to the right is 0x45670123 
****************************************************************************/ 

1 

• “_crotl - _crotr — Rotate Bits of Character Value” on page 117 

• “_rotl - _rotr — Rotate Bits of Unsigned Integer” on page 514 

• “_srotl - _srotr — Rotate Bits of Unsigned Short Value” on page 558 

• “<builtin.h>” on page 801 

• “<stdlib.h>” on page 816 
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Iseek — Move File Pointer 

Format linclude <io.h> /* constants in <stdio.h> */ 

long lseek(int handle, long offset, int origin); 


Description Language Level: XPG4, Extension 


1 seek moves any file pointer associated with handle to a new location that is offset 
bytes from the origin. The next operation on the file takes place at the new 
location. The origin must be one of the following constants, defined in <stdio.h>: 


Origin 

SEEKJSET 

SEEK_CUR 

SEEK_END 


Definition 

Beginning of file 

Current position of file pointer 

End of file. 


1 seek can reposition the pointer anywhere in a file. The pointer can also be 
positioned beyond the end of the file; the data between the EOF and the new file 
position is undefined. (See “_chsi ze — Alter Length of File” on page 92 for more 
information on extending the length of the file.) An attempt to position the pointer 
before the beginning of the file causes an error. 

Note: In earlier releases of C Set ++, 1 seek began with an underscore (_lseek). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _lseek to lseek for you. 


Return Value 1 seek returns the offset, in bytes, of the new position from the beginning of the 
file. A return value of -1L indicates an error, and 1 seek sets errno to one of the 
following values: 


Value 

EBADF 

EINVAL 

EOS2ERR 


Meaning 

The file handle is incorrect. 

The value for origin is incorrect, or the position specified by offset 
is before the beginning of the file. 

The call to the operating system was not successful. 


On devices incapable of seeking (such as keyboards and printers), lseek returns -1 
and sets errno to EOS2ERR. 
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This example opens the file sample.dat and, if successful, moves the file pointer to 
the eighth position in the file. The example then attempts to read bytes from the file, 
starting at the new pointer position, and reads them into the buffer. 


#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 
#include <fcntl,h> 
#include <string.h> 


int main(void) 

{ 

long length; 
int fh; 

char buffer[20]; 


memset(buffer, '\0', 20); /* Initialize the buffer */ 

printf("\nCreating sample.dat.\n"); 
system("echo Sample Program > sample.dat"); 
if (-1 == (fh = open("sample.dat", 0_RDWR|0_APPEND))) { 
perror("Unable to open sample.dat."); 
exit(EXIT_FAILURE); 

} 

if (-1 == lseek(fh, 7, SEEK_SET)) { /* place the file pointer at the */ 

perror("Unable to lseek"); /* eighth position in the file */ 

close(fh); 

return EXIT_FAILURE; 

} 

if (8 != read(fh, buffer, 8)) { 

perror("Unable to read from sample.dat."); 
close(fh); 

return EXIT_FAILURE; 

} 

printf("Successfully read in the fol1owing:\n%s.\n", buffer); 
close(fh); 
return 0; 


/**************************************************************************** 

The output should be: 

Creating sample.dat. 

Successfully read in the following: 

Program . 

****************************************************************************/ 

} 



“_chsi ze — Alter Length of File” on page 92 
“fseek — Reposition File Position” on page 273 
“_tel 1 — Get Pointer Position” on page 655 
“<io.h>” on page 804 
“<stdio.h>” on page 815 
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_ltoa — Convert Long Integer to String 

Format linclude <std1ib.h> 

char *_ltoa(long value, char *string, int radix); 

Description Language Level: Extension 

_ltoa converts the digits of the given long integer value to a character string that 
ends with a null character and stores the result in string. The radix argument 
specifies the base of value; it must be in the range 2 to 36. If radix equals 10 and 
value is negative, the first character of the stored string is the minus sign (-). 

Note: The space allocated for string must be large enough to hold the returned 
string. The function can return up to 33 bytes, including the null character (\0). 

Return Value _ltoa returns a pointer to string. There is no error return value. 

This example converts the long integer -255L to a decimal, binary, and hex value, 
and stores its character representation in the array buffer. 

#inc1ude <stdio.h> 

#inc1ude <stdlib.h> 

int main(void) 

{ 

char buffer[35]; 
char *p; 

p = _ltoa(-255L, buffer, 10); 

printf("The result of _1toa(-255) with radix of 10 is %s\n", p); 
p = _ltoa(-255L, buffer, 2); 

printf("The result of _1toa(-255) with radix of 2\n is %s\n", p); 
p = _ltoa(-255L, buffer, 16); 

printf("The result of _1toa(-255) with radix of 16 is %s\n", p); 
return 0; 

/**************************************************************************** 

The output should be: 

The result of _ltoa(-255) with radix of 10 is -255 
The result of _ltoa(-255) with radix of 2 
is 11111111111111111111111100000001 
The result of _ltoa(-255) with radix of 16 is ffffffOl 
****************************************************************************/ 

} 

• “atol — Convert Character String to Long Integer” on page 67 

• “_ecvt — Convert Floating-Point to Character” on page 192 

• “_fcvt — Convert Floating-Point to String” on page 217 

• “_gcvt — Convert Floating-Point to String” on page 294 

• “_i toa — Convert Integer to String” on page 368 

• “strtol — Convert Character String to Long Integer” on page 625 
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• “_ul toa — Convert Unsigned Long Integer to String” on page 716 

• “wcstol — Convert Wide-Character to Long Integer” on page 782 

• “<stdlib.h>” on page 816 
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_lxchg — Exchange Integer Value with Memory 

Format linclude <builtin.h> 

int _Builtin _1xchg(volati1e int *lockptr, int value); 

Description Language Level: Extension 

_lxchg puts the specified value in the memory location pointed to by lockptr , and 

returns the value that was previously in that location. 

Use this function to implement fast-RAM semaphores to serialize access to a critical 
resource (so that only one thread can use it at a time). You can also use OS/2 
semaphores to serialize resource access, but they are slower. Typically you would 
create both a fast-RAM semaphore and an OS/2 semaphore for the resource. For 
more details about OS/2 semaphores and how to use them, see the Control Program 
Guide and Reference. 

To implement a fast-RAM semaphore, allocate a volatile memory location lockptr 

(for_lxchg, it must be of type int), and statically initialize it to 0 to indicate that 

the resource is free (not being used). To give a thread access to the resource, call 

_lxchg from the thread to exchange a non-zero value with that memory location. If 

_lxchg returns 0, the thread can access the resource; it has also set the memory 

location so that other threads can tell the resource is in use. When your thread no 
longer needs the resource, call_lxchg again to reset the memory location to 0. 

If_lxchg returns a non-zero value, another thread is already using the resource, and 

the calling thread must wait for access. You could then use the OS/2 semaphore to 
inform your waiting thread when the resource is unlocked by the thread currently 
using it. 

It is important that you set the memory to a nonzero value when you are using the 
resource. You can use the same nonzero value for all threads, or a unique value for 
each. 

Note: _lxchg is a built-in function, which means it is implemented as an inline 

instruction and has no backing code in the library. For this reason: 

• You cannot take the address of_lxchg. 

• You cannot parenthesize a call to_lxchg. (Parentheses specify a call to the 

function's backing code, and_lxchg has none.) 

Return Value _lxchg returns the previous value stored in the memory location pointed to by 

lockptr. 
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This example creates five separate threads, each associated with a State. At most 
two threads can have a State of Eating at the same time. When a thread calls 
PickUpChopSticks, that function checks the states of the preceding threads to make 

sure they are not already Eating, If the call to_lxchg is successful, the thread has 

locked the Lock semaphore and can change its State to Eating. It then calls_lxchg 

a second time to unlock the semaphore, and returns. 


If_lxchg cannot lock the semaphore, another thread has it locked. The current 

thread then suspends itself briefly with DosSleep and tries again. The semaphore is 
used to ensure that two threads cannot simultaneously change their State to Eating, 
which would cause a deadlock. (Note that although the semaphore solves the 
problem of deadlock, it is not an optimal solution; some threads may never get the 
semaphore or the State of Eating.) 

Note: You must compile this example with the multithread (/Gm) option. The 
example runs in an infinite loop; press Ctrl-C to end it. 

#pragma strings(readonly) 

#define INCL_D0S 
#include <os2,h> 

#include <stdlib.h> 

#include <stdio.h> 

#include <bui1tin.h> 

typedef enum { 

Thinking, 

Eating. 

Hungry 
} States; 

#define UNLOCKED 0 
#define LOCKED 1 
#define NUM_PHILOSOPHERS 5 

static volatile int Lock; 

static States State[NUM_PHILOSOPHERS]; 

static const int NameMap[NUM_PHILOSOPHERS] = {0, 1, 2, 3, 4}; 
static const char * const Names[NUM_PHILOSOPHERS] = {"Plato", 

"Socrates", 

"Kant", 

"Hegel", 

"Nietsche"}; 
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void PickUpChopSticks(int Ident); 
void PutDownChopSticks(int Ident); 
void Think(int Ident); 
void Eat(int Ident); 

void _0ptlink StartPhilosopher(void *pldent); 

void _0ptlink StartPhilosopher(void *pldent) 

{ 

int Ident = *(int *)pldent; 
while (1) { 

State[Ident] = Hungry; 

printf("%s hungry.\n", Names[Ident]); 

PickUpChopSticks(Ident); 

Eat(Ident); 

PutDownChopSticks(Ident); 

Think(Ident); 



int main(int argc, char *argv[], char *envp[]) 

{ 

int i; 

unsigned long tid; 

for (i = 0; i < NUM_PHILOSOPHERS; i++) { 

tid = _beginthread(StartPhilosopher, NULL, 8192, (void *)&NameMap[i]); 
if (tid == -1) { 

printf("Unable to start %s.\n", Names[i]); 

} 

el se { 

printf("%s started with Thread Id = %d.\n". Names[i], tid); 

} 

} 

DosWaitThread(&tid, DCWW_WAIT); 
return 0; 

} 

void PickUpChopSticks(int Ident) 

{ 

while (1) { 

if (State[(Ident + NUM_PHILOSOPHERS - 1) % NUM_PHILOSOPHERS] != Eating && 
State[(Ident + 1) % NUM_PHILOSOPHERS] != Eating && 

!_lxchg(&Lock, LOCKED)) { 

State[Ident] = Eating; 

_lxchg(&Lock, UNLOCKED); 

return; 


Chapter 3. Library Functions 399 



lxchg 


el se { 

DosSleep(l); 

} 

} 

} 


void PutDownChopSticks(int Ident) 

{ 

State[Ident] = Thinking; 

} 

void Eat(int Ident) 

{ 

printf("%s eating.\n". Names[Ident]); 
DosSleep(l); 


void Think(int Ident) 

{ 

printf("%s thinking.\n", Names[Ident]); 
DosSleep(l); 


/**************************************************************************** 

The output should be similar to : 

Plato started with Thread Id = 2. 

Socrates started with Thread Id = 3. 

Kant started with Thread Id = 4. 

Hegel started with Thread Id = 5. 

Nietsche started with Thread Id = 6. 

Plato hungry. 

Plato eating. 

Socrates hungry. 

Kant hungry. 

Kant eating. 

Hegel hungry. 

Nietsche hungry. 

Kant thinking. 

Plato thinking. 

Plato hungry. 

Plato eating. 

Kant hungry. 

Kant eating. 

****************************************************************************/ 



“_cxchg — Exchange Character Value with Memory” on page 134 

“_sxchg — Exchange Integer Value with Memory” on page 641 

“<builtin.h>” on page 801 
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jnakepath 

Format 

Description 


Return Value 


Create Path 

linclude <stdlib.h> 

void _makepath(char *path, char *drive, char *dir, char *fname, char *ext ); 
Language Level: Extension 

_makepath creates a single path name, composed of a drive letter, directory path, file 
name, and file name extension. 

The path argument should point to an empty buffer large enough to hold the 
complete path name. The constant _MAX_PATH, defined in <stdlib.h>, specifies 
the maximum size allowed for path. The other arguments point to the following 
buffers containing the path name elements: 

drive A letter (A, B, ...) corresponding to the desired drive and an optional 
following colon, jnakepath inserts the colon automatically in the 
composite path name if it is missing. If drive is a null character or an 
empty string, no drive letter or colon appears in the composite path string. 

dir The path of directories, not including the drive designator or the actual file 
name. The trailing slash is optional, and either slash (/) or backslash (\) or 
both can be used in a single dir argument. If a trailing slash or backslash 
is not specified, it is insetted automatically. If dir is a null character or an 
empty string, no slash is inserted in the composite path string. 

frame The base file name without any extensions. 

ext The actual file name extension, with or without a leading period. 

jnakepath inserts the period automatically if it does not appear in ext. If 
ext is a null character or an empty string, no period is inserted in the 
composite path string. 

The size limits on the above four fields are those specified by the constants 
_MAX_DRIVE, _MAX_DIR, _MAX_FNAME, and _MAX_EXT, which are defined 
in <stdlib.h>. The composite path should be no larger than the _MAX_PATH 
constant also defined in <stdlib.h>; otherwise, the operating system does not handle 
it correctly. 

Note: No checking is done to see if the syntax of the file name is correct. 

There is no return value. 


Chapter 3. Library Functions 401 



makepath 



This example builds a file name path from the specified components. 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

char path_buffer[_MAX_PATH]; 
char drive[_MAX_DRIVE]; 
char dir [_MAX_DIR]; 
char fname[_MAX_FNAME]; 
char ext[_MAX_EXT]; 


_makepath(path_buffer, "c", "qc\\bob\\eclibrefWe", "makepath", "c"); 
printf("Path created with jnakepath: %s\n\n", path_buffer); 

_splitpath(path_buffer, drive, dir, fname, ext); 

printf("Path extracted with _splitpath:\n"); 

printf("drive: %s\n", drive); 

printf("directory: %s\n", dir); 

printf("fi1e name: %s\n", fname); 

printf("extension: %s\n", ext); 

return 0; 


/•k-k-k-k-k-kic-k-k-k-k-klc-k-k'k-k-klc-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-kick-k-k-k-klck-k'k-kick-kick-k-klck-k-k 

The output should be: 

Path created with jnakepath: c:qc\bob\eclibref\e\makepath.c 

Path extracted with _splitpath: 
drive: c: 

directory: qc\bob\eclibref\e\ 
file name: makepath 
extension: .c 

****************************************************************************/ 

} 



“_ful 1 path — Get Full Path Name of Partial Path” on page 287 
“_spl i tpath — Decompose Path Name” on page 552 
“<stdlib.h>” on page 816 
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malloc — Reserve Storage Block 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *malloc(size_t size); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

malloc reserves a block of storage of size bytes. Unlike calloc, malloc does not 
initialize all elements to 0. 


Heap-specific, tiled, and debug versions of this function (_umal loc, _tmal loc, and 
_debug_mal 1 oc) are also available, malloc always operates on the default heap. For 
more information about memory management, see Managing Memory in the 
Programming Guide. 


Return Value mal loc returns a pointer to the reserved space. The storage space to which the 

return value points is suitably aligned for storage of any type of object. The return 
value is NULL if not enough storage is available, or if size was specified as zero. 



This example prompts for the number of array entries you want and then reserves 
enough space in storage for the entries. If mal 1 oc was successful, the example assigns 
values to the entries and prints out each entry; otherwise, it prints out an error. 


#include <stdio.h> 
#include <stdlib.h> 


int main(void) 

{ 

long *array; 
long *index; 
i nt i; 
int num; 


/* start of the array */ 

/* index variable */ 

/* index variable */ 

/* number of entries of the array */ 


printf("Enter the size of the array\n"); 
scanf("%i", &num); 
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/* allocate num entries */ 

if ((index = array = malloc(num *sizeof(long))) != NULL) { 

for (i = 0; i < num; ++i) /* put values in array */ 

*index++ = i; /* using pointer notation */ 

for (i = 0; i < num; ++i) /* print the array out */ 

printf("array[ %i ] = %i\n", i, arrayfi]); 

} 

else { /* malloc error */ 

perror("0ut of storage"); 
abort(); 

} 

return 0; 


/**************************************************************************** 
The output should be similar to: 

Enter the size of the array 
5 

array[ 0 ] = 0 

array[ 1 ] = 1 

array[ 2 ] = 2 

array[ 3 ] = 3 

array[ 4 ] = 4 

■k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-kle-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k'k-k-k-k-k-klck-k-k-k-klck-klck-k/ 

} 



“cal loc — Reserve and Initialize Storage” on page 80 

“_debug_mal 1 oc — Allocate Memory” on page 145 

“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 

“_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 

“free — Release Storage Blocks” on page 263 

“_mheap — Query Memory Heap for Allocated Object” on page 433 

“_msi ze — Return Number of Bytes Allocated” on page 441 

“real loc — Change Reserved Storage Block Size” on page 484 

“_tmal 1 oc — Reserve Tiled Storage Block” on page 667 

“_umal 1 oc — Reserve Memory Blocks from User Heap” on page 717 

“<malloc.h>” on page 810 

“<stdlib.h>” on page 816 
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jnatherr - 

Format 

Description 


Process Math Library Errors 

linclude <math.h> 

int _matherr(struct exception *x ); 

Language Level: Extension 

jnatherr processes errors generated by the functions in the math library. The math 
functions call jnatherr whenever they detect an error. The jnatherr function 
supplied with the VisualAge C++ library performs no error handling and returns 0 to 
the calling function. 

You can provide a different definition of jnatherr to carry out special error 
handling. Be sure to use the /NOE link option, if you are using your own jnatherr 
function. For VisualAge C++ compiler, you can use the /B option on the i cc 
command line to pass the /NOE option to the linker, as in the following: 
icc /B"/N0E" yourfile.c 

When an error occurs in a math routine, jnatherr is called with a pointer to the 
following structure (defined in <math.h>) as an argument: 

struct exception { 
int type; 
char *name; 

double argl, arg2, retval; 

}; 


The type field specifies the type of math error. It has one of the following values, 
defined in <math.h>: 


Value 

DOMAIN 

OVERFLOW 

UNDERFLOW 

TLOSS 

PLOSS 

SING 


Meaning 

Argument domain error 
Overflow range error 
Underflow range error 
Total loss of significance 
Partial loss of significance 
Argument singularity. 


PLOSS is provided for compatibility with other compilers; VisualAge C++ does not 
generate this value. 


The name is a pointer to a null-ended string containing the name of the function that 
caused the error. The argl and arg2 fields specify the argument values that caused 
the error. If only one argument is given, it is stored in argl. The retval is the 
default return value; you can change it. 
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Return Value 



The return value from _matherr must specify whether or not an error actually 
occurred. If _matherr returns 0, an error message appears, and errno is set to an 
appropriate error value. If jnatherr returns a nonzero value, no error message 
appears and errno remains unchanged. 

This example provides a jnatherr function to handle errors from the log or loglO 
functions. The arguments to these logarithmic functions must be positive double 
values, jnatherr processes a negative value in an argument (a domain error) by 
returning the log of its absolute value. It suppresses the error message normally 
displayed when this error occurs. If the error is a zero argument or if some other 
routine produced the error, the example takes the default actions. 

Note: You must compile this example with the /B"/N0E" compiler option. 
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#include <math.h> 

#include <string.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

int value; 

printf("Trying to evaluate loglO(-lOOO.OO) will create a math exception.\n"); 
value = logl0(-1000.00); 

printf("The _matherr() exception handler evaluates the expression to\n"); 
printf("1oglO(-lOOO.OO) = %d\n", value); 
return 0; 

/**************************************************************************** 

The output should be: 

Trying to evaluate loglQ(-lOOO.OG) will create a math exception, 
inside jnatherr 

The _matherr() exception handler evaluates the expression to 
logl0(-1000.00) = 3 

****************************************************************************/ 


int _matherr(struct exception *x) 

{ 

printf("inside _matherr\n"); 
if (DOMAIN == x->type) { 

if (0 == strcmp(x->name, "log")) { 
x->retval = log(-(x->argl)); 
return EXIT_FAILURE; 

} 

el se 

if (0 == strcmp(x->name, "1ogl0")) { 
x->retval = 1og10(-(x->arg1)); 
return EXIT_FAILURE; 

} 


return 0; 

} 


/* Use default actions */ 


• “1 og — Calculate Natural Logarithm” on page 387 

• “log 10 — Calculate Base 10 Logarithm” on page 388 

• “<math.h>” on page 811 
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max — Return Larger of Two Values 

Format linclude <stdlib.h> 

type max [type a, type b ); 

Description Language Level: Extension 

max compares two values and determines the larger of the two. The data type can be 
any arithmetic data type, signed or unsigned. Both arguments must have the same 
type for each call to max. 

Note: Because max is a macro, if the evaluation of the arguments contains side 
effects (post-increment operators, for example), the results of both the side effects and 
the macro will be undefined. 


Return Value max returns the larger of the two values. 



This example prints the larger of the two values, a and b. 

#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

int a = 10; 
int b = 21; 


printf("The larger of %d and %d is %d\n", a, b, max(a, b)); 
return 0; 

/•k-k-k-k-k-k'k-k-kle-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-klck-k-k-k-k-k-k-k-k-k-k-k 

The output should be: 

The larger of 10 and 21 is 21 

■k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-kick-k-k-k-k-klck-k-k-k-k-k-k-k-k-k-k/ 

) 



“mi n — Return Lesser of Two Values” on page 435 
“<stdlib.h>” on page 816 
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maxcol1 — 

Format 

Description 

Return Value 



Return Maximum Collating Element 

linclude <collate.h> 
collel_t maxcol 1 (void); 

Language Level: Extension 

maxcol 1 determines the largest possible value of a collating element in the current 
locale. 


maxcol 1 returns the largest collating element. 

This example sets the current locale to several different locales, and uses maxcoll to 
determine the largest collating element for each. 

#include <stdio.h> 

#include <1ocale.h> 

#include <col1 ate.h> 

Idefine LOCALEMAX 4 

static char *1ocales[LOCALEMAX] = 

{"ES_ES.IBM-850", "EN_US.IBM-850", "FR_FR.IBM-850", "JA_JP.IBM-932"}; 

int main(void) 

{ 

int locnum; 

for (locnum = 0; locnum < LOCALEMAX; locnum++) { 
if (NULL == setlocale(LC_ALL, locales[locnum])) 

printf("setlocale(LC_ALL, \"%s\") failed.\n", locales[locnum]); 
el se { 

printf("The current locale is %s.\n", 1ocales[1ocnum]); 
printf(" maxcol1() returned %d\n", maxcol1()); 



return 0; 

/**************************************************************************** 
The output should be similar to : 

The current locale is ES_ES.IBM-850. 

maxcol1 () returned 263 
The current locale is ENJJS.IBM-850, 
maxcol1() returned 255 
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The current locale is FR_FR.IBM-850. 

maxcoll () returned 255 
The current locale is JA_JP.IBM-932, 
maxcoll() returned 64587 

****************************************************************************/ 

} 



“cclass — Return Characters in Character Class” on page 82 
“col 1 equi v — Return List of Equivalent Collating Elements” on page 101 
“col 1 order — Return List of Collating Elements” on page 103 
“col 1 range — Calculate Range of Collating Elements” on page 105 
“col 1 tostr — Return String for Collating Element” on page 107 
“getmccol 1 — Get Next Collating Element from String” on page 306 
“getwmccol 1 — Get Next Collating Element from Wide String” on page 319 
“i smccol 1 el — Identify Multi-Character Collating Element” on page 358 
“strtocol 1 — Return Collating Element for Suing” on page 619 
“<collate.h>” on page 802 
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mblen — Determine Length of Multibyte Character 

Format linclude <stdlib.h> 

int mblen(const char *string, size_t n ); 

Description Language Level: ANSI, SAA, XPG4 

mblen determines the length in bytes of the multibyte character pointed to by string. 
A maximum of n bytes is examined. 

The behavior of mblen is affected by the LC_CTYPE category of the current locale. 

Return Value If string is NULL, mblen returns 0. 

Note: On platforms that support shift states, mblen can also return a nonzero value 
to indicate that the multibyte encoding is state-dependent. Because VisualAge C++ 
does not support state-dependent encoding, mblen always returns 0 when string is 
NULL. 

If string is not NULL, mblen returns: 

• 0 if string points to the null character 

• The number of bytes comprising the multibyte character 

• The value -1 if string does not point to a valid multibyte character. 

This example uses mbl en and mbtowc to convert a multibyte character into a single 
wide character. 



Chapter 3. Library Functions 411 



mblen 


#include <stdio.h> 

#include <stdlib.h> 

#include <wchar.h> 

#include <1ocale.h> 

int main(void) 

{ 

char mb_string[] = "\x81\x41\x81\xc2" "b"; 

int length; 

wchar_t widechar; 

if (NULL s= setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

length = mblen(mb_string, MB_CUR_MAX); 
mbtowc(&widechar, mb_string, length); 

printf("The wide character %lc has length of %d.\n", widechar, length); 
return 0; 

/***************************************************'***'**'*'******'***'**'*'*'**'**** 
The output should be similar to : 

The wide character A has length of 2. 

■k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-klc-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-klck-klck-klck-k'k-k-k/ 

} 



“mbrl en — Calculate Length of Multibyte Character” on page 413 
“mbrtowc — Convert Multibyte Character to Wide Character” on page 415 
“mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 
“mbstowcs — Convert Multibyte String to Wide-Character String” on page 420 
“mbtowc — Convert Multibyte Character to Wide Character” on page 422 
“setlocale — Set Locale” on page 530 
“strlen — Determine String Length” on page 593 

“wcrtomb — Convert Wide Character to Multibyte Character” on page 747 
“wcsl en — Calculate Length of Wide-Character String” on page 763 
“wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 
“wctomb — Convert Wide Character to Multibyte Character” on page 793 
“<locale.h>” on page 806 
“<stdlib.h>” on page 816 
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mbrlen — Calculate Length of Multibyte Character 

Format linclude <wchar.h> 

size_t mbrlen(const char *string, size_t n, 
mbstate_t *state); 

Description Language Level: ANSI 93 

mbrl en is a restartable version of mbl en and performs the same function. It 
determines the length in bytes of the multibyte character pointed to by string. A 
maximum of n bytes are examined. 

With mbrlen, you can switch from one multibyte string to another. On platforms that 
support shift states, state represents the initial shift state of the string (0). If you 
read in only part of the string, mbrlen sets state to the string's shift state at the point 
you stopped. You can then call mbrlen again for that string and pass in the updated 
state value to continue reading where you left off. 

Note: Because OS/2 does not have shift states, the state parameter is provided 
only for compatibility with other ANSI/ISO platforms. VisualAge C++ ignores the 
value passed for state. 

The behavior of mbrl en is affected by the LC_CTYPE category of the current locale. 
Return Value If string is a null pointer, mbrlen returns 0. 

If string is not a null pointer, mbrl en returns the first of the following that applies: 

0 If the next n or fewer bytes complete the valid multibyte character that 
corresponds to the null wide character. 

positive 

If the next n or fewer bytes complete the valid multibyte character; the value 
returned is the number of bytes that complete the multibyte character. 

-2 If the next n bytes form an incomplete (but potentially valid) multibyte 
character, and all n bytes have been processed. 

-1 If an encoding error occurs (when the next n or fewer bytes do not form a 
complete and valid multibyte character), mbrlen sets errno to EILSEQ. 

This example uses mbrlen to determine the length of the strings mbsl and mbs2. 
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#include <wchar.h> 
#include <stdio.h> 

#include <stdlib.h> 
#include <1ocale.h> 


int main(void) 

{ 

char mbsl[] = "abc"; 

char mbs2[] = "\x81\x41" "a" "\x81\xcl"; 

mbstate_t ssl = 0; 

mbstate_t ss2 = 0; 

size_t lengthl, length2; 


if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 


lengthl = mbrlen(mbsl, MB_CUR_MAX, &ssl); 

length2 = mbrlen(mbs2, MB_CUR_MAX, &ss2); 

lengthl += mbrlen(mbsl + lengthl, MB_CUR_MAX, &ss1); 

length2 += mbrlen(mbs2 + length2, MB_CUR_MAX, &ss2); 

lengthl += mbrlen(mbsl + lengthl, MB_CUR_MAX, &ss1); 

length2 += mbrlen(mbs2 + length2, MB_CUR_MAX, &ss2); 

printf("Length of the first multibyte string = %d\n", 
printf("Length of the second multibyte string = %d\n", 
return 0; 


/* 

first 

char 

*/ 

/* 

first 

char 

*/ 

/* 

second 

char 

*/ 

/* 

second 

char 

*/ 

/* 

thi rd 

char 

*/ 

/* 

thi rd 

char 

*/ 

engthl); 




1ength2); 


/**************************************************************************** 

The output should be similiar to : 

Length of the first multi byte string = 3 
Length of the second multi byte string = 5 

****************************************************************************/ 

} 



“mbl en — Determine Length of Multibyte Character” on page 411 
“mbtowc — Convert Multibyte Character to Wide Character” on page 422 
“mbrtowc — Convert Multibyte Character to Wide Character” on page 415 
“mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 
“setl ocal e — Set Locale” on page 530 

“wcrtomb — Convert Wide Character to Multibyte Character” on page 747 
“wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 
“<locale.h>” on page 806 
“<wchar.h>” on page 821 
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mbrtowc — Convert Multibyte Character to Wide Character 

Format linclude <wchar.h> 

size_t mbrtowc (wchar_t *pwc, const char *string, 
size_t n, mbstate_t *ps ); 

Description Language Level: ANSI 93 

mbrtowc is a restartable version of mbtowc, and performs the same function. It first 
determines the length of the multibyte character pointed to by string. It then 
converts the multibyte character to the corresponding wide character, and stores the 
converted character in the location pointed to by pwc, if pwc is not a null pointer. A 
maximum of n bytes are examined. 

With mbrtowc, you can switch from one multibyte string to another. On systems that 
support shift states, ps represents the initial shift state of the string (0). If you read in 
only part of the string, mbrtowc sets ps to the string's shift state at the point you 
stopped. You can then call mbrtowc again for that string and pass in the updated ps 
value to continue reading where you left off. 

Note: Because OS/2 does not have shift states, the ps parameter is provided only 
for compatibility with other ANSI/ISO platforms. VisualAge C++ ignores the value 
passed for ps. 

The behavior of mbrtowc is affected by the LC_CTYPE category of the current 
locale. 

Return Value If string is a null pointer, mbrtowc returns 0. 

If string is not a null pointer, mbrtowc returns the first of the following that applies: 

0 If the next n or fewer bytes complete the valid multibyte character that 
corresponds to the null wide character. 

positive 

If the next n or fewer bytes complete the valid multibyte character; the value 
returned is the number of bytes that complete the multibyte character. 

-2 If the next n bytes form an incomplete (but potentially valid) multibyte 
character, and all n bytes have been processed. 

-1 If an encoding error occurs (when the next n or fewer bytes do not form a 
complete and valid multibyte character), mbrtowc sets errno to EILSEQ. 
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This example uses mbrl en to move to the second character in a string, then calls 
mbrtowc to convert the multibyte character to a wide character. 


#include <wchar.h> 
#include <stdio.h> 

#include <stdlib.h> 
#include <1ocale.h> 


int main(void) 

{ 

char mbsl[] = "abc"; 

char mbs2[] = "\x81\x41\x81\x42" " m "; 

mbstate_t ssl = 0; 

mbstate_t ss2 = 0; 

size_t lengthl, length2; 

wchar_t wcl, wc2; 

if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

lengthl = mbrlen(mbsl, MB_CUR_MAX, &ssl); 

length2 = mbrlen(mbs2, MB_CUR_MAX, &ss2); 

mbrtowc(&wcl, mbsl + lengthl, MB_CUR_MAX, &ss1); 

mbrtowc(&wc2, mbs2 + length2, MB_CUR_MAX, &ss2); 

printf("The second wide character in mbsl is: <%lc>\n", wcl); 

printf("The second wide character in mbs2 is: <%lc>\n", wc2); 

return 0; 

/**************************************************************************** 

The output should be similiar to : 

The second wide character in mbsl is: <b> 

The second wide character in mbs2 is: < B> 

****************************************************************************/ 



“mbl en — Determine Length of Multibyte Character” on page 411 
“mbrl en — Calculate Length of Multibyte Character” on page 413 
“mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 
“setlocale — Set Locale” on page 530 

“wcrtomb — Convert Wide Character to Multibyte Character” on page 747 
“wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 
“<locale.h>” on page 806 
“<wchar.h>” on page 821 
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mbsinit — 

Format 

Description 

Return Value 



Test Object for Initial State 

linclude <wchar.h> 

int mbsinit(mbstate_t *state ); 

Language Level: Extension 

mbsinit determines whether the state describes an initial conversion state. 

Note: mbsinit is provided only for compatibility with EBCDIC systems that 
support conversion or shift states. OS/2 does not use shift states for multibyte 
character encoding. 

If state is a null pointer or points to 0, mbsinit returns a nonzero value. If state 
points to any other value, mbsinit returns 0. On systems that support shift states, 
mbsinit returns nonzero if state describes an initial conversion state, or 0 otherwise. 

This example checks the conversion state to see if it is in the initial state. 

linclude <wchar.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

char *string = "ABC"; 
mbstate_t state = 0; 
wchar_t wc; 

mbrtowc(&wc, string, MB_CUR_MAX, &state); 
if (0 != mbsinit(&state)) 

printf("In initial conversion state.\n"); 
return 0; 

^■k'k-k-k-k-k-k-k'k'k-k-k-k-k'k-kick'k-k-k-k-k-kick-k-kick-k-k-k'k-k-k-k-k-k-k-k-k-k-kick-k-kick-k-k-k-k-k-kick-k-k-k-k-k-k-k-k-k-k-k-k-k-kick'k-k 

The output should be similar to : 

In initial conversion state. 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kick'k-kick-k-k-k-k-k-kick-k-k-k-k-k-kick-k-kick-k-kick-k-k-k-k-k-kick-k-k-k-k-k-kick-k-kick'k/ 

1 

• “mbrlen — Calculate Length of Multibyte Character” on page 413 

• “mbrtowc — Convert Multibyte Character to Wide Character” on page 415 

• “mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 

• “setl ocal e — Set Locale” on page 530 

• “wcrtomb — Convert Wide Character to Multibyte Character” on page 747 

• “wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 

• “<locale.h>” on page 806 

• “<wchar.h>” on page 821 
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mbsrtowcs 

Format 

Description 


Return Value 


Convert Multibyte String to Wide-Character String 

linclude <wchar.h> 

size_t mbsrtowcs (wchar_t *dest, const char **src, 
size_t len, mbstate_t *ps); 

Language Level: ANSI 93 

mbsrtowcs is a restartable version of mbstowcs, and performs the same function. It 
converts the sequence of multibyte characters from the array indirectly pointed to by 
src into a sequence of corresponding wide characters, and then stores the converted 
characters in the array pointed to by dest. 

Conversion continues up to and including the terminating wchar_t null character. The 
terminating null wide character is also stored. Conversion stops earlier if a sequence 
of bytes does not form a valid multibyte character, or when l en codes have been 
stored into the array pointed to by dest. Each conversion takes place as if by a call 
to the mbrtowc function. 

mbsrtowcs assigns the object pointed to by src either a null pointer (if conversion 
stopped because a terminating null character was reached) or the address just past the 
last multibyte character converted. 

With mbsrtowcs, you can switch from one multibyte string to another. On platforms 
that support shift states, ps represents the initial shift state of the string (0). If you 
read in only part of the string, mbsrtowcs sets ps to the string's shift state at the point 
you stopped. You can then call mbsrtowcs again for that string and pass in the 
updated ps value to continue reading where you left off. 

Note: Because OS/2 does not have shift states, the ps parameter is provided only 
for compatibility with other ANSI/ISO platforms. VisualAge C++ ignores the value 
passed for ps. 

The behavior of mbsrtowcs is affected by the LC_CTYPE category of the current 
locale. 

mbsrtowcs returns the number of multibyte characters successfully converted, not 
including the terminating null character. If dest is a null pointer, the value of len is 
ignored and mbsrtowcs returns the number of elements required for the converted 
wide characters. 

If the input string contains an invalid multibyte character, mbsrtowcs sets errno to 
EILSEQ and returns (size_t) — 1. 
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This example uses mbsrtowcs to convert the multibyte characters in the arrays mbsl 
and mbs2, and store them in the arrays wcsl and wcs2. 

#include <wchar.h> 

#inc1ude <stdio.h> 

#include <stdlib. h> 

#include <1ocale.h> 

Idefine SIZE 10 

int main(void) 

{ 


char 

mbsl[] = 

"abc"; 

char 

mbs2[] = 

"\x81\x41" "m" "\x81\x42 

const char 

*pmbsl = 

mbsl; 

const char 

*pmbs2 = 

mbs2; 

mbstate_t 

ssl = 0; 



mbstate_t ss2 = 0; 

wchar_t wcsl[SIZE], wcs2[SIZE]; 

if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXITFAILURE); 

} 

mbsrtowcs(wcsl, &pmbsl, SIZE, &ssl); 
mbsrtowcs(wcs2, &pmbs2, SIZE, &ss2); 

printf("The first wide character string is %ls.\n", wcsl); 
printf("The second wide character string is %ls.\n", wcs2); 
return 0; 

/**************************************************************************** 
The output should be similiar to : 

The first wide character string is abc. 

The second wide character string is Am B. 
****************************************************************************/ 


• “mbl en — Determine Length of Multibyte Character” on page 411 

• “mbrlen — Calculate Length of Multibyte Character” on page 413 

• “mbrtowc — Convert Multibyte Character to Wide Character” on page 415 

• “mbstowcs — Convert Multibyte String to Wide-Character String” on page 420 

• “setl ocal e — Set Locale” on page 530 

• “wcrtomb — Convert Wide Character to Multibyte Character” on page 747 

• “wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 

• “<locale.h>” on page 806 

• “<wchar.h>” on page 821 
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mbstowcs — 

Format 

Description 


Return Value 



Convert Multibyte String to Wide-Character String 

linclude <stdlib.h> 

size_t mbstowcs(wchar_t *dest, const char *string, size_t Zen); 

Language Level: ANSI, SAA, XPG4 

mbstowcs converts the multibyte character string pointed to by string into the 
wide-character array pointed to by dest. Depending on the encoding scheme used by 
the code set, the multibyte character string can contain any combination of single-byte 
or double-byte characters. 

The conversion stops after len bytes in dest are filled or after a wchar_t null 
character is encountered. The terminating null character is converted to a wide 
character with the value 0; characters that follow it are not processed. 

The behavior of mbstowcs is affected by the LC_CTYPE category of the current 
locale. 

If successful, mbstowcs returns the number of characters converted and stored in 
dest, not counting the terminating null character. The string pointed to by dest ends 
with a null character unless mbstowcs returns the value len. 

If it encounters an invalid multibyte character, mbstowcs returns (size_t)-l. If dest 
is a null pointer, the value of len is ignored and mbstowcs returns the number of 
elements required for the converted wide characters. 

This example uses mbstowcs to convert the multibyte character mbs to a a wide 
character string and store it in wcs. 
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#include <wchar.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <1ocale.h> 

#define SIZE 10 

int main(void) 

{ 

char mbs[] = "\x81\x41" "m" "\x81\x42"; 

wchar_t wcs[SIZE]; 

if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

mbstowcs(wcs, mbs, SIZE); 

printf("The wide character string is %ls.\n", wcs); 
return 0; 

/**************************************************************************** 
The output should be similiar to : 

The wide character string is Am B. 

****************************************************************************/ 

} 


• “mbl en — Determine Length of Multibyte Character” on page 411 

• “mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 

• “mbtowc — Convert Multibyte Character to Wide Character” on page 422 

• “setl ocal e — Set Locale” on page 530 

• “wcslen — Calculate Length of Wide-Character String” on page 763 

• “wcstombs — Convert Wide-Character String to Multibyte String” on page 784 

• “<locale.h>” on page 806 

• “<stdlib.h>” on page 816 


Chapter 3. Library Functions 421 




mbtowc 


mbtowc — Convert Multibyte Character to Wide Character 

Format linclude <stdlib.h> 

int mbtowc(wchar_t *pwc, const char * string, size_t n ); 

Description Language Level: ANSI, SAA, XPG4 

mbtowc first determines the length of the multibyte character pointed to by string. It 
then converts the multibyte character to the corresponding wide character, and stores 
it in the location pointed to by pwc. if pwc is not a null pointer, mbtowc examines a 
maximum of n bytes from string. 

If pwc is a null pointer, the multibyte character is not converted. 

The behavior of mbtowc is affected by the LC_CTYPE category of the current locale. 

Return Value If string is null, mbtowc returns 0. 

Note: On platforms that support shift states, mbtowc can also return a nonzero value 
to indicate that the multibyte encoding is state dependent. Because VisualAge C++ 
does not support state-dependent encoding, mbtowc always returns 0 when string is 
NULL. 


If string is not NULL, mbtowc returns: 

• The number of bytes comprising the converted multibyte character, if n or fewer 
bytes form a valid multibyte character. 

• 0 if string points to the null character. 

• -1 if string does not point to a valid multibyte character, and the next n bytes 
do not form a valid multibyte character. 



This example uses mbtowc to convert the second multibyte character in mbs to a wide 
character. 
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#include <stdio.h> 

#include <stdlib.h> 

#include <wchar.h> 

#include <1ocale.h> 

int main(void) 

{ 

char mb_string[] = "\x81\x41\x81\x42" "c" "\x00"; 

int length; 

wchar_t widechar; 

if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

length = mblen(mb_string, MB_CUR_MAX); 

length = mbtowc(&widechar, mb_string + length, MB_CUR_MAX); 

printf("The wide character %lc has length of %d.\n", widechar, length); 

return 0; 

/**************************************************************************** 
The output should be similar to : 

The wide character B has length of 2. 

****************************************************************************/ 

} 


• “mbl en — Determine Length of Multibyte Character” on page 411 

• “mbrtowc — Convert Multibyte Character to Wide Character” on page 415 

• “mbstowcs — Convert Multibyte String to Wide-Character String” on page 420 

• “setl ocal e — Set Locale” on page 530 

• “wcslen — Calculate Length of Wide-Character String” on page 763 

• “wctomb — Convert Wide Character to Multibyte Character” on page 793 

• “<locale.h>” on page 806 

• “<stdlib.h>” on page 816 
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memccpy — Copy Bytes 

Format #include <string.h> /* also in <memory.h> */ 

void *memccpy(void *dest, void *src, int c, unsigned cnt) ; 

Description Language Level: Extension 

memccpy copies bytes from src to dest, up to and including the first occurrence of 
the character c or until cnt bytes have been copied, whichever comes first. 

Return Value If the character c is copied, memccpy returns a pointer to the byte in dest that 
immediately follows the character. If c is not copied, memccpy returns NULL. 

This example copies up to 55 characters, or until it copies the '. 1 character, from the 
source to the buffer. 

#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

char source[60]; 
char result[60]; 

int main(void) 

{ 

memcpy(source, "This is the string. This part won't be copied.", 55); 
if (NULL == memccpy(result, source, 55)) { 
printf("Error in copying source.\n"); 
exit(EXIT_FAILURE); 

} 

else 

printf("%s\n", result); 
return 0; 

/•k-k-kle-k-k'k-k-k'k-k-kle-k-kle-k-k'k-k-k'k-k-k'k-k-klc-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k'k'k-k-k-k-k-k-k-k-k'k 

The output should be: 

This is the string. 

■k-k-k-klt-k-k-k-k-k'k-k-kle-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-kie-k-k-k-k-k'k-k-k-k-k-k'k-kit/ 

} 

• “memchr — Search Buffer” on page 425 

• “memcmp — Compare Buffers” on page 426 

• “memcpy — Copy Bytes” on page 428 

• “memmove — Copy Bytes” on page 431 

• “memset — Set Bytes to Value” on page 432 

• “<memory.h>” on page 811 

• “<string.h>” on page 818 
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memchr — Search Buffer 

Format linclude <string.h> /* also in <memory.h> */ 

void *memchr(const void *buf, int c, size_t count); 

Description Language Level: ANSI, SAA, XPG4, Extension 

memchr searches the first count bytes of buf for the first occurrence of c converted to 
an unsigned character. The search continues until it finds c or examines count bytes. 

Return Value memchr returns a pointer to the location of c in buf. It returns NULL if c is not 
within the first count bytes of buf. 

This example finds the first occurrence of “x” in the string that you provide. If it is 
found, the string that starts with that character is printed. 

#include <stdio.h> 

#include <string.h> 

int main(int argc.char **argv) 

{ 

char *result; 
if (argc != 2) 

printf("Usage: %s string\n", argv[0]); 
el se { 

if ((result = memchr(argv[l], 'x', strlen(argv[l]))) != NULL) 
printf("The string starting with x is %s\n", result); 
el se 

printf("The letter x cannot be found in the string\n"); 

} 

return 0; 

/**************************************************************************** 

If the program is passed the argumrnt boxing, the output should be: 

The string starting with x is xing 

****************************************************************************/ 

i 

• “memccpy — Copy Bytes” on page 424 

• “memcmp — Compare Buffers” on page 426 

• “memcpy — Copy Bytes” on page 428 

• “memi cmp — Compare Bytes” on page 429 

• “memmove — Copy Bytes” on page 431 

• “memset — Set Bytes to Value” on page 432 

• “strchr — Search for Character” on page 566 

• “<memory.h>” on page 811 

• “<string.h>” on page 818 
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memcmp — Compare Buffers 

Format #include <string.h> /* also in <memory.h> */ 

int memcmp(const void *bufl, const void *buf2, size_t count); 


Description Language Level: ANSI, SAA, XPG4, Extension 

memcmp compares the first count bytes of bufl and buf2. 


Return Value memcmp returns a value indicating the relationship between the two buffers as 
follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

bufl less than buf2 
bufl identical to buf2 
bufl greater than buf2 



This example compares first and second arguments passed to main to determine 
which, if either, is greater. 

#include <stdio.h> 

#include <string.h> 


int main(int argc.char **argv) 

{ 

int len; 
int result; 


if (argc != 3) { 

printf("Usage: %s stringl string2\n", argv[0]); 

} 

else { 


/* Determine the length to be used for comparison */ 

if (strlen(argv[l]) < strlen(argv[2])) 
len = strlen(argv[l]); 
else 

len = strlen(argv[2]); 
result = memcmp(argv[1], argv[2], len); 

printf("When the first %i characters are compared,\n", len); 
if (0 — result) 

printf("\"%s\" is identical to \"%s\"\n", argv[l], argv[2]); 
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el se 

if (result < 0) 

printf("\"%s\" is less than \"%s\“\n", argv[l], argv[2]); 
el se 

printf("\"%s\" is greater than \"%s\"\n", argv[l], argv[2]); 


return 0; 

/**************************************************************************** 
If the program is passed the arguments "firststring secondstring", 
the output should be: 

When the first 11 characters are compared, 

"firststring" is less than "secondstring" 
****************************************************************************/ 


• “memchr — Search Buffer” on page 425 

• “memcpy — Copy Bytes” on page 428 

• “memi cmp — Compare Bytes” on page 429 

• “memmove — Copy Bytes” on page 431 

• “memset — Set Bytes to Value” on page 432 

• “strcmp — Compare Strings” on page 567 

• “<string.h>” on page 818 
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memcpy — Copy Bytes 

Format linclude <string.h> /* also <memory.h> */ 

void *memcpy(void *dest, const void *src, size_t count)-. 


Description Language Level: ANSI, SAA, XPG4, Extension 

memcpy copies count bytes of src to dest. The behavior is undefined if copying 
takes place between objects that overlap. (The memmove function allows copying 
between objects that may overlap.) 

Return Value memcpy returns a pointer to dest. 

This example copies the contents of source to target. 

linclude <string.h> 
linclude <stdio.h> 

Idefine MAX_LEN 80 

char source[MAX_LEN] = "This is the source string"; 
char target[MAX_LEN] = "This is the target string"; 

int main(void) 

{ 

printf("Before memcpy, target is \"%s\"\n", target); 
memcpy(target, source, sizeof(source)); 
printf("After memcpy, target becomes \"%s\"\n", target); 
return 0; 

/**************************************************************************** 

The output should be: 

Before memcpy, target is "This is the target string" 

After memcpy, target becomes "This is the source string" 
****************************************************************************/ 

} 




“memccpy — Copy Bytes” on page 424 
“memchr — Search Buffer” on page 425 
“memcmp — Compare Buffers” on page 426 
“memmove — Copy Bytes” on page 431 
“memset — Set Bytes to Value” on page 432 
“strcpy — Copy Strings” on page 573 
“<string.h>” on page 818 
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memi cmp — Compare Bytes 

Format linclude <string.h> /* also in <memory.h> */ 

int memicmp(void *bufl, void *buf2, unsigned int cnt ); 


Description Language Level: Extension 

memicmp compares the first cnt bytes of bufl and buf2 without regard to the case of 
letters in the two buffers. The function converts all uppercase characters into 
lowercase and then performs the comparison. 


Return Value The return value of memicmp indicates the result as follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

bufl less than buf2 
bufl identical to buf2 
bufl greater than buf2. 



This example copies two strings that each contain a substring of 29 characters that are 
the same except for case. The example then compares the first 29 bytes without 
regard to case. 

#include <stdio.h> 

#inc1ude <string.h> 


char first[100],second[100]; 


int main(void) 

{ 

int result; 


strcpy(first, "Those Who Will Not Learn From History"); 

strcpy(second, "THOSE WHO WILL NOT LEARN FROM their mistakes"); 

printf("Comparing the first 29 characters of two strings.\n"); 

result = memicmp(first, second, 29); 

printf("The first 29 characters of String 1 are "); 

if (result < 0) 

printf("less than String 2.\n"); 
el se 

if (0 == result) 

printf ("equal to String 2.\n"); 
el se 

printf("greater than String 2.\n"); 
return 0; 

/**************************************************************************** 
The output should be: 

Comparing the first 29 characters of two strings. 

The first 29 characters of String 1 are equal to String 2 
****************************************************************************/ 

} 
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“memchr — Search Buffer” on page 425 
“memcmp — Compare Buffers” on page 426 
“memcpy — Copy Bytes” on page 428 
“memmove — Copy Bytes” on page 431 
“memset — Set Bytes to Value” on page 432 
“strcmp — Compare Strings” on page 567 
“<memory.h>” on page 811 
“<string.h>” on page 818 
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memmove — Copy Bytes 

Format linclude <string.h> /* also in <memory.h> */ 

void *memmove(void *dest, const void *src, size_t count); 

Description Language Level: ANSI, SAA, XPG4, Extension 

memmove copies count bytes of src to dest. memmove allows copying between objects 
that may overlap as if src is first copied into a temporary array. 


Return Value memmove returns a pointer to dest. 

This example copies the word shiny from position target + 2 to position target + 8. 

#inc1ude <string.h> 

#inc1ude <stdio.h> 

Idefine SIZE 21 

char target[SIZE] = "a shiny white sphere"; 

int main(void) 

{ 

char *p = target+8; /* p points at the starting character 

of the word we want to replace */ 
char *source = target+2; /* start of "shiny" */ 

printf("Before memmove, target is \"%s\"\n", target); 
memmove(p, source, 5); 

printf("After memmove, target becomes \"%s\"\n", target); 
return 0; 

/**************************************************************************** 

The output should be: 

Before memmove, target is "a shiny white sphere" 

After memmove, target becomes "a shiny shiny sphere" 
****************************************************************************/ 




“memccpy — Copy Bytes” on page 424 
“memchr — Search Buffer” on page 425 
“memcmp — Compare Buffers” on page 426 
“memcpy — Copy Bytes” on page 428 
“memset — Set Bytes to Value” on page 432 
“strcpy — Copy Strings” on page 573 
“<string.h>” on page 818 
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memset — Set Bytes to Value 

Format linclude <string.h> /* also in <memory.h> */ 

void *memset(void *dest, int c, size_t count); 

Description Language Level: ANSI, SAA, XPG4, Extension 

memset sets the first count bytes of dest to the value c. The value of c is converted 
to an unsigned character. 


Return Value memset returns a pointer to dest. 

This example sets 10 bytes of the buffer to A and the next 10 bytes to B. 

linclude <string.h> 
linclude <stdio.h> 

Idefine BUFSIZE 20 

int main(void) 

{ 

char buffer[BUF_SIZE+l]; 
char *string; 

memset(buffer, 0, sizeof(buffer)); 
string = memset(buffer, 'A', 10); 
printf("\nBuffer contents: %s\n", string); 
memset(buffer+10, 'B 1 , 10); 
printf("\nBuffer contents: %s\n", buffer); 
return 0; 

/**************************************************************************** 

The output should be: 

Buffer contents: AAAAAAAAAA 
Buffer contents: AAAAAAAAAABBBBBBBBBB 

****************************************************************************/ 




“memccpy — Copy Bytes” on page 424 

“memchr — Search Buffer” on page 425 

“memcmp — Compare Buffers” on page 426 

“memcpy — Copy Bytes” on page 428 

“memi cmp — Compare Bytes” on page 429 

“memmove — Copy Bytes” on page 431 

“strnset - strset — Set Characters in String” on page 603 

“<memory.h>” on page 811 

“<string.h>” on page 818 
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jnheap — Query Memory Heap for Allocated Object 

Format linclude <umalloc.h> 

Heap_t _mheap(void *ptr ); 

Description Language Level: Extension 

_mheap determines from which heap the object specified by ptr was allocated. The 
ptr must be a valid pointer that was returned from a runtime allocation function 
(_ucal 1 oc, mal 1 oc, real 1 oc, and so on). If the pointer is not valid, the results of 
jnheap are undefined. 

For more information about creating and using heaps, see the chapter on Managing 
Memory in the Programming Guide. 

Return Value jnheap returns the handle of the heap from which the object was allocated. If the 
object was allocated from the runtime heap, _mheap returns _RUNTIME_HEAP. If 
the object passed to jnheap is NULL, jnheap returns NULL. If the object is not 
valid, jnheap either returns NULL (depending on how closely the storage pointed to 
resembles a valid object), or an exception occurs. 

This example allocates a block of memory from the heap, then uses jnheap to 
determine which heap the block came from. 

#inc1ude <stdlib.h> 

#inc1ude <stdio.h> 

#inc1ude <umal1oc.h> 

int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = mal1oc(10))) { 

puts("Could not allocate memory block."); 
exit (EXIT JAI LURE); 

} 

printf("Handle of heap used is 0x%x\n", _mheap(ptr)); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

Handle of heap used is 0x70000 

****************************************************************************/ 

i 

• “Managing Memory” in the Programming Guide 

• “jnsize — Return Number of Bytes Allocated” on page 441 

• “_ucreate — Create a Memory Heap” on page 690 

• “_ustats — Get Information about Heap” on page 732 
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• “<umalloc.h>” on page 820 
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min — Return Lesser of Two Values 


Format 

Description 

Return Value 



linclude <stdlib.h> 
type min [type a, type b ); 

Language Level: Extension 

mi n compares two values and determines the smaller of the two. The data type can 
be any arithmetic data type, signed or unsigned. The type must be the same for both 
arguments to min. 

Note: Because min is a macro, if the evaluation of the arguments contains side 
effects (post-increment operators, for example), the results of both the side effects and 
the macro will be undefined. 

mi n returns the smaller of the two values. 

This example prints the smaller of the two values, a and b. 

#inc1ude <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

int a = 10; 
int b = 21; 

printf("The smaller of %d and %d is %d\n", a, b, min(a, b)); 
return 0; 

/**************************************************************************** 

The output should be: 

The smaller of 10 and 21 is 10 

****************************************************************************/ 

i 

• “max — Return Larger of Two Values” on page 408 

• “<stdlib.h>” on page 816 
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mkdir — Create New Directory 

Format #include <direct.h> 

int mkdir(char *pathname); 


Description Language Level: XPG4, Extension 

mkdi r creates a new directory with the specified pathname. Because only one 
directory can be created at a time, only the last component of pathname can name a 
new directory. 

Note: In earlier releases of C Set ++, mkdi r began with an underscore (_mkdi r). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _mkdi r to mkdi r for you. 


Return Value mkdi r returns the value 0 if the directory was created. A return value of -1 
indicates an error, and errno is set to one of the following values: 

Value Meaning 

EACCESS The directory was not created; the given name is the name of an 
existing file, directory, or device. 

ENOENT The pathname was not found. 



This example creates two new directories: one at the root on drive C:, and one in the 
tmp subdirectory of the current working directory. 


#include <stdio.h> 
#include <direct.h> 
#include <string.h> 


int main(void) 

{ 

char *dirl,*dir2; 


/* Create the directory "aleng" in the root directory of the C: drive. */ 

dirt = "c:\\aleng"; 
if (0 == (mkdir(dirl))) 

printf("%s directory was created.\n", dirl); 
else 

printf("%s directory was not created.\n", dirl); 
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/* Create the subdirectory "simon" ir the current directory. */ 

dir2 = "simon"; 

if (0 == (mkdir(dir2))) 

printf("%s directory was created.\n", dir2); 
el se 

printf("%s directory was not created.\n", dir2); 

/* Remove the directory "aleng" from the root directory of the C: drive. */ 

printf("Removing directory 'aleng' from the root directory.\n"); 
if (rmdir(dirl)) 
perror(NULL); 
el se 

printf("%s directory was removed.\n", dirl); 

/* Remove the subdirectory "simon" from the current directory. */ 

printf("Removing subdirectory 'simon' from the current directory.\n"); 
if (rmdir(dir2)) 
perror(NULL); 
el se 

printf("%s directory was removed.\n", dir2); 
return 0; 

/**************************************************************************** 
The output should be: 

c:\aleng directory was created, 
simon directory was created. 

Removing directory 'aleng' from the root directory. 
c:\aleng directory was removed. 

Removing subdirectory 'simon' from the current directory, 
simon directory was removed. 

****************************************************************************/ 


• “chdi r — Change Current Working Directory” on page 87 

• “_getcwd — Get Path Name of Current Directory” on page 300 

• “_getdcwd — Get Full Path Name of Current Directory” on page 302 

• “rmdi r — Remove Directory” on page 499 

• “<direct.h>” on page 803 
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mktime — Convert Local Time 


Format #i ncl tide <time.h> 

time_t mktime(struct tm *time ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

mktime converts local time, stored as a tm structure pointed to by time , into a time_t 
structure suitable for use with other time functions. The values of some structure 
elements pointed to by time are not restricted to the ranges shown for “gmtime — 
Convert Time” on page 321. 

The values of tm_wday and tm_yday passed to mktime are ignored and are assigned 
their correct values on return. 

Note: The time and date functions begin at 00:00:00 Coordinated Universal Time, 
January 1, 1970. 


Return Value mktime returns the calendar time having type time_t. The value (time_t) (-1) is 
returned if the calendar time cannot be represented. 



This example prints the day of the week that is 40 days and 16 hours from the 
current date. 

#include <stdio.h> 

#include <time.h> 


char *wday[] = { "Sunday", "Monday", "Tuesday", "Wednesday", 

"Thursday", "Friday", "Saturday" } ; 


int main(void) 

{ 

time_t tl,t3; 
struct tm *t2; 

tl = time(NULL); 
t2 = 1ocaltime(&tl); 
t2->tm_mday += 40; 
t2->tm_hour += 16; 
t3 = mktime(t2); 

printf("40 days and 16 hours from now, it will be a %9s \n", wday[t2->tm_wday 

]); 

return 0; 

/■***********************************************************■****'**'***'***'*'**'** 
The output should be similar to: 

40 days and 16 hours from now, it will be a Sunday 

} 
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• “asctime — Convert Time to Character String” on page 55 
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• “ctime — Convert Time to Character String” on page 129 

• “gmtime— Convert Time” on page 321 

• “localtime — Convert Time” on page 385 

• “t i me — Determine Current Time” on page 666 

• “<time.h>” on page 819 
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modf — Separate Floating-Point Value 

Format linclude <math.h> 

double modf (double x, double *intptr ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

modf breaks down the floating-point value x into fractional and integral parts. The 
signed fractional portion of x is returned. The integer portion is stored as a double 
value pointed to by intptr. Both the fractional and integral parts are given the same 
sign as x. 


Return Value modf returns the signed fractional portion of x. 



This example breaks the floating-point number -14.876 into its fractional and integral 
components. 

#include <math.h> 


int main(void) 

{ 

double x,y,d; 


x = -14.876; 

y = modf(x, &d); 

printf("x = %1f\n", x); 

printf("Integral part = %lf\n", d); 

printf("Fractional part = %lf\n", y); 

return 0; 


/**************************************************************************** 

The output should be: 


x = -14.876000 

Integral part = -14.000000 

Fractional part = -0.876000 

****************************************************************************/ 

} 



“fmod — Calculate Floating-Point Remainder” on page 242 
“frexp — Separate Floating-Point Value” on page 270 
“1 dexp — Multiply by a Power of Two” on page 372 
“<math.h>” on page 811 
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msize — Return Number of Bytes Allocated 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

size_t _msize(void *ptr ) 

Description Language Level: Extension 

_msi ze determines the number of bytes that were allocated to the pointer argument 
ptr. The ptr must have been returned from one of the runtime memory allocation 
functions (_ucal 1 oc, mal 1 oc, _treal 1 oc, and so on). 

You cannot pass the argument of an object that has been freed. 

Return Value _msi ze returns the number of bytes allocated. If the argument is not a valid pointer 
returned from a memory allocation function, the return value is undefined. If NULL is 
passed, _msize returns 0. 

This example displays the size of an allocated object from mal loc. 

#inc1ude <stdlib.h> 

#inc1ude <stdio.h> 

int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = malloc(lO))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x', 5); 

printf("The size of the allocated object is %u.\n",_msize(ptr)); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

The size of the allocated object is 10. 
****************************************************************************/ 
i 


• “cal loc — Reserve and Initialize Storage” on page 80 

• “mal loc — Reserve Storage Block” on page 403 

• “real loc — Change Reserved Storage Block Size” on page 484 

• “_tcal 1 oc — Reserve Tiled Storage Block” on page 647 

• “_tmal 1 oc — Reserve Tiled Storage Block” on page 667 

• “_trealloc — Reallocate Tiled Storage Block” on page 679 

• “<malloc.h>” on page 810 
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• “<stdlib.h>” on page 816 
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nl_langinfo 

Format 

Description 


Return Value 



— Retrieve Locale Information 

linclude <nl_types.h> 
linclude <langinfo.h> 
char *nl_langinfo(nl_item item); 

Language Level: XPG4 

n 1 _1 angi nfo retrieves from the current locale the string that describes the requested 
information specified by i tem. 

The constant names and values for item are defined in <1 angi nfo. h>. For a list of 
macros that define the constants used to identify the information queried in the 
current locale, see the table of defined macros under “<langinfo.h>” on page 804. 

You cannot retrieve the following information for the current locale: 

t_fmt_amp m 

era 

era_year 
era_d_fmt 
al t_digits 
t_fmt_ampm 
al t_digits 


nl_l angi nfo returns a pointer to a null-terminated string containing information 
about the active language or cultural area. The active language or cultural area is 
determined by the most recent setlocale call. Subsequent calls to the function may 
modify the array that the return value points to. Your own code cannot modify the 
array. 

If item is not valid, nl_l angi nfo returns a pointer to an empty string. 

This example uses nl_J angi nfo to retrieve the current codeset name. 

linclude <nl_types.h> 

#include <1anginfo.h> 

#include <stdio.h> 

int main(void) 

{ 

printf("Current codeset is %s\n", nl_1anginfo(CODESET)); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

Current codeset is IBM-850 

****************************************************************************/ 

i 
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“localdtconv — Return Date and Time Formatting Convention” on page 379 
“localeconv — Retrieve Information from the Environment” on page 381 
“setlocale — Set Locale” on page 530 
“<langinfo.h>” on page 804 
“<nl_types.h>” on page 812 


444 


VisualAge C++ C Library Reference 




onexit 


onexit — Record Termination Function 

Format linclude <stdlib.h> 

onexit_t _onexit(onexit_t func ); 


Description Language Level: Extension 

_onexi t records the address of a function func to call when the program ends 
normally. Successive calls to _onexit create a stack of functions that run in a 
last-in, first-out order. The functions passed to _onexit cannot take parameters. 

You can record up to 32 termination functions with calls to _onexit and atexit. If 
you exceed 32 functions, _onexit returns the value NULL. 

Note: For portability, use the ANSI/ISO standard atexit function, which is 
equivalent to _onexi t. 


Return Value If successful, _onexit returns a pointer to the function; otherwise, it returns a NULL 
value. 



This example specifies and defines four distinct functions that run consecutively at 
the completion of main. 

#include <stdio.h> 

#inc1ude <stdlib.h> 


int fnl(void) 

{ 

printf("next.\n"); 

} 


int fn2(void) 

{ 

printf("run 

} 


int fn3(void) 

{ 

printf("is "); 

} 
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int fn4(void) 

{ 

printf("This "); 

} 


int main(void) 

{ 

_onexit(fnl); 

_onexit(fn2); 

_onexit(fn3); 

_onexit(fn4); 

printf("This is run first.\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

This is run first. 

This is run next. 

****************************************************************************/ 



“abort — Stop a Program” on page 47 

“atexit — Record Program Termination Function” on page 62 
“exit — End Program” on page 204 
“_exi t — End Process” on page 205 
“<stdlib.h>” on page 816 
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open — Open File 

Format linclude <io.h> 

linclude <fcntl.h> 
linclude <sys\stat.h> 

int open(char *pathname, int of lag, int pmode ); 

Description Language Level: XPG4, Extension 

open opens the file specified by pathname and prepares the file for subsequent 
reading or writing as defined by of lag. open can also prepare the file for reading 
and writing. 

The of lag is an integer expression formed by combining one or more of the 
following constants, defined in <fcntl ,h>. To specify more than one constant, join 
the constants with the bitwise OR operator (I); for example, 0_CREAT I 0_TEXT. 

Oflag Meaning 

0_APPEND Reposition the file pointer to the end of the file before every write 
operation. 

0_CREAT Create and open a new file. This flag has no effect if the file 
specified by pathname exists. 

0_EXCL Return an error value if the file specified by pathname exists. This 
flag applies only when used with 0_CREAT. 

0_RD0NLY Open the file for reading only. If this flag is given, neither 
0_RDWR nor 0_WR0NLY can be given. 

0_RDWR Open the file for reading and writing. If this flag is given, neither 
0_RD0NLY nor 0_WR0NLY can be given. 

0_TRUNC Open and truncate an existing file to 0 length. The file must have 
write permission. The contents of the file are destroyed, and 
0_TRUNC cannot be specified with 0_RD0NLY. 

0_WR0NLY Open the file for writing only. If this flag is given, neither 
0_RD0NLY nor 0_RDWR can be given. 

0_BINARY Open the file in binary (untranslated) mode. 

0_TEXT Open the file in text (translated) mode. 

If neither 0_BINARY or 0_TEXT is specified, the default will be 0_TEXT; it is an 
error to specify both 0_BINARY and 0_TEXT. You must specify one of the access 
mode flags, 0_RD0NLY, 0_WR0NLY, or 0_RDWR. There is no default. 
Warning: Use 0_TRUNC with care; it destroys the complete contents of an 
existing file. 

For more details on text and binary modes and their differences, see “Stream 
Processing” in the Programming Guide. 
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Return Value 



The pmode argument is an integer expression containing one or both of the constants 
S_IWRITE and S_IREAD, defined in <sys\stat.h>. The pmode is required only 
when 0_CREAT is specified. If the file exists, pmode is ignored. Otherwise, pmode 
specifies the permission settings for the file. These are set when the new file is 
closed for the first time. The meaning of the pmode argument is as follows: 


Value 

S_IWRITE 

S_IREAD 

S_IREAD I S IWRITE 


Meaning 

Writing permitted 
Reading permitted 
Reading and writing permitted. 


If write permission is not given, the file is read-only. Under the OS/2 operating 
system, all files are readable; you cannot give write-only permission. The modes 
SJWRITE and SJREAD I SJWRITE are equivalent. 


open applies the current file permission mask to pmode before setting the permissions. 
(See “umask — Sets File Mask of Current Process” on page 719.) 

Note: In earlier releases of C Set ++, open began with an underscore (_open). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _open to open for you. 


open returns a file handle for the opened file. A return value of -1 indicates an 
error, and errno is set to one of the following values: 


Value 

EACCESS 

EEXIST 

EMFILE 

EINVAL 

ENOENT 

EOS2ERR 


Meaning 

The given pathname is a directory; or the file is read-only but an 
open for writing was attempted; or a sharing violation occurred. 
The 0_CREAT and 0_EXCL flags are specified, but the named 
file already exists. 

No more file handles are available. 

An incorrect argument was passed. 

The file or pathname were not found. 

The call to the operating system was not successful. 


This example opens the file edopen.dat by creating it as a new file, truncating it if it 
exists, and opening it so it can be read and written to. The open command issued 
also grants permission to read from and write to the file. 
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#include <io.h> 

#include <stdio.h> 

#include <fcntl.h> 

#include <sys\stat.h> 

#include <std1ib.h> 

int main(void) 

{ 

int fh; 

if (-1 == (fh = open("edopen.dat", 0_CREAT|0_TRUNC|0_RDWR, 

S_IREAD|SIWRITE))) { 
perror("Unable to open edopen.dat"); 
return EXIT_FAILURE; 

} 

printf("File was successfully opened.\n"); 
if (-1 == close(fh)) { 
perror("close error"); 
return EXIT_FAILURE; 

} 

return 0; 

/**************************************************************************** 
The output should be: 

File was successfully opened. 

****************************************************************************/ 

} 

• “close — Close File Associated with Handle” on page 99 

• “creat — Create New File” on page 115 

• “fdopen — Associates Input Or Output With File” on page 219 

• “fopen — Open Files” on page 243 

• “_sopen — Open Shared File” on page 545 

• “umask — Sets File Mask of Current Process” on page 719 

• “<fcntl.h>” on page 803 

• “<io.h>” on page 804 

• “<sys\stat.h>” on page 819 
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outp — Write Byte to Output Port 

Format linclude <conio.h> /* also in <builtin.h> */ 

int _outp( const unsigned int port, const int value ); 

Description Language Level: Extension 

_outp writes a byte value to the specified port. The port number must be an 
unsigned integer value within the range 0 to 65 535 inclusive. The byte value must 
be within the range 0 to 255 inclusive. 

Note: _outp is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _outp. 

• You cannot parenthesize a call to _outp. (Parentheses specify a call to the 
function's backing code, and _outp has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 


Return Value _outp returns the integer value that was output to the specified port. There is no 
error return value, and _outp does not set errno. 



This example uses _outp to write a byte to a specified output port and return the data 
written. 

#include <bui1tin.h> 


#define LOWER 0 
#define UPPER1 255 
#define UPPER2 65535 

int Add1(int j); 

static int g; 

enum fruit {apples=10, bananas, cantaloupes}; 
enum fruit f = cantaloupes; 
int arr[] = {cantaloupes, bananas, apples}; 
struct 
{ 

int i; 
char ch; 

} st; 

int main(void) 

{ 

static int i; 

volatile const int c = 0; 
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st.i = c - bananas; 
g = _outp(LOWER,apples); 
i s _outp(255, 0); 

/* ============================= */ 

/* Types of port number passed : */ 

/* - */ 

i = _outp(UPPER2,UPPERl); /* - Idefine constant */ 

i = _outp(st.i, bananas); /* - element of structure */ 

i = _outp(f,arr[l]); /* - enumerated variable */ 

i = _outp(_inp(arr[2]),apples); /* - return value from a */ 

/* builtin function call */ 

/*-*/ 

i = _outp(_outp(apples,Addl(LOWER)),6); 
return 0; 


int Add 1 (int j) 

{ 

j += l; 
return j; 


• “_i np — Read Byte from Input Port” on page 340 

• “_inpw — Read Unsigned Short from Input Port” on page 344 

• “_inpd — Read Doubleword from Input Port” on page 342 

• “_outpw — Write Word to Output Port” on page 454 

• “_outpd — Write Double Word to Output Port” on page 452 

• “<builtin.h>” on page 801 

• “<conio.h>” on page 802 
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outpd — Write Double Word to Output Port 

Format linclude <conio.h> /* also in <builtin.h */ 

unsigned long _outpd( const unsigned int port, const unsigned long value ); 

Description Language Level: Extension 

_outpd writes an unsigned long value to the specified port. The port number must 
be a value within the range 0 to 65 535 inclusive. The unsigned long value must be 
within the range 0 to 4 294 967 295 inclusive. 

Note: _outpd is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _outpd. 

• You cannot parenthesize a call to _outpd. (Parentheses specify a call to the 
function's backing code, and _outpd has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 


Return Value _outpd returns the unsigned long value that was output to the specified port. 
There is no error return value, and _outpd does not set errno. 



This example uses _outpd to write a doubleword value to a specified output port and 
return the data written. 

#include <bui1tin.h> 


#define LOWER 0 
#define UPPER1 65535 
#define UPPER2 4294967295 

int Add1(int j); 

volatile long g; 

enum fruit {apples=10, bananas, cantaloupes}; 
enum fruit f = cantaloupes; 
int arr[] = {cantaloupes, bananas, apples}; 
uni on 
{ 

volati1e int i; 
volatile char ch; 

} un; 

int main(void) 

{ 

unsigned long 1; 
volatile const short c = 0; 
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un.i = bananas * f; 
g = _outpd(0,LOWER); 




/* 


= */ 



/* 

Types of port number passed 

: */ 



/* 


- */ 

= outpd(UPPERl, 

UPPER2); 

/* 

- Idefine constant 

*/ 

= outpd(un.i ,f) 

; 

/* 

- element of union 

*/ 

II 

O 

sz 

-O 

Q. 

CL 

Q- 

n 

apples); 

/* 

- return value from a 

*/ 



/* 

function call 

*/ 



/* 


- */ 


1 = _outpd(_outpw(255,Addl(L0WER)),6); 
return 0; 


int Addl(int j) 

{ 

j += l; 
return j; 


• “_i np — Read Byte from Input Port” on page 340 

• “_inpw — Read Unsigned Short from Input Port” on page 344 

• “_inpd — Read Doubleword from Input Port” on page 342 

• “_outp — Write Byte to Output Port” on page 450 

• “_outpw — Write Word to Output Port” on page 454 

• “<builtin.h>” on page 801 

• “<conio.h>” on page 802 
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outpw — Write Word to Output Port 

Format linclude <conio.h> /* also in <builtin.h */ 

unsigned short _outpw( const unsigned int port, const unsigned short word ); 

Description Language Level: Extension 

_outpw writes an unsigned short word to the specified port. The port number must 
be an unsigned integer value within the range 0 to 65 535 inclusive. The unsigned 
short word must be in the range 0 to 65 535. 

Note: _outpw is a built-in function, which means it is implemented as an inline 
instruction and has no backing code in the library. For this reason: 

• You cannot take the address of _outpw. 

• You cannot parenthesize a call to _outpw. (Parentheses specify a call to the 
function's backing code, and _outpw has none.) 

You can run code containing this function only at ring zero. Otherwise, an invalid 
instruction exception is generated. 


Return Value _outpw returns the value that was output to the specified port. There is no error 
return value, and _outpw does not set errno. 



This example uses _outpw to write an unsigned short value to a specified output port 
and return the data written. 

#include <bui1tin.h> 

#define LOWER 0 
#define UPPER 65535 

int Add1(int j); 

unsigned int g; 


int main(void) 

{ 

enum fruit {apples = 10, bananas, cantaloupes}; 

enum fruit f = cantaloupes; 

int arr[] = {cantaloupes, bananas, apples}; 
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unsigned short s; 
static int i = 0; 
volatile const int c = 255; 


g = _outpw(cantaloupes, i); 

/* ============================= */ 

/* Types of port number passed : */ 

/* - */ 

s = _outpw(UPPER, LOWER); /* - Idefine constant */ 

s = _outpw(c, Add1(255)); /* - constant */ 

s = _outpw(_inpw(arr[2]),apples); /* - return value from a */ 

/* builtin function call */ 

/*-*/ 

s = _outpw(_outpw(bananas .UPPER),6); 
return 0; 


int Addl(int j) 

{ 

j += l; 
return j; 


• “_i np — Read Byte from Input Port” on page 340 

• “_inpw — Read Unsigned Short from Input Port” on page 344 

• “_inpd — Read Doubleword from Input Port” on page 342 

• “_outp — Write Byte to Output Port” on page 450 

• “_outpd — Write Double Word to Output Port” on page 452 

• “<builtin.h>” on page 801 

• “<conio.h>” on page 802 
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_parmdwords — Get Number of dwords in Parameter List 

Format linclude <stdlib.h> /* also in <builtin.h> */ 

unsigned char _parmdwords(void); 

Language Level: Extension 

Description The_parmdwords function returns the hidden parameter passed in the AL register 

for _System linkage calls. The hidden parameter contains the size of the parameter 

list that is passed to the function containing the call to_parmdwords. The size is in 

doublewords (dwords), and can be between 0 and 255. If the parameter list is larger 
than 255 dwords, the hidden parameter contains the 8 least significant bits of the 
value. 

Note: To use_parmdwords, you must compile with the /Gp+ option to include the 

support for it. 

This function allows the implementer of a function to increase the number of 
parameters the function takes without changing the name of the function. The new 

version of the function can call_parmdwords to check the size of the parameter list 

and determine whether the call was written for the earlier version of the function or 
for the extended version. 


Warning: The_parmdwords function has several limitations: 

1. Because it is a built-in function and has no backing code in the library: 

• You cannot take the address of_parmdwords. 

• You cannot parenthesize a_parmdwords function call because parentheses 

specify a call to the backing code for the function. 

2. The_parmdwords function can only be used for functions with the _System 

linkage type. If you use it with other linkage types, an error message is 
generated, and your program will not compile correctly. 

3. Not all vendors implement the hidden parameter in the AL register, so 

_parmdwords may have incorrect results when you use it in a function that is 

called from code compiled by other compilers. 


Return Value The_parmdwords function returns the size of the parameter list passed to the 

function in units of dwords. 



This example shows two versions of an API that prints out messages. The second 

version uses_parmdwords to determine whether the call was intended for the 

original or the updated version. 
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#include <stdlib.h> 

#include <stdio.h> 

#pragma 1inkage(ErrorHandler, system) 

int ErrorHandler(int MessgageNum.int Severity); /* Extended version of API */ 

/* Old version API prototype -- int ErrorHandler(int MessageNum); */ 

Idefine MESSAGE1 1 

Idefine MESSAGE2 2 

Idefine INFORMATIONAL 3 

#define WARNING 2 

Idefine ERROR 1 

Idefine FATAL 0 

int ErrorHandler(int MessageNum,int Severity) 

{ 

int rc = 0; 


switch ((int)_parmdwordsO) { 

case 2 : /* Extended version with Severity parameter */ 

switch (Severity) { 
case FATAL : 

printf("Fatal Error:"); 
break; 

case ERROR : 

printf("Error:"); 
break; 

case WARNING : 

printf("Warning:"); 
break; 

case INFORMATIONAL : 

printf("Informational:"); 
break; 
default : 

rc = EXIT_FAILURE; 

printf("Bad Severity Number"); 


/* intentional fall through */ 

case 1 : /* Old version of API without Severity parameter */ 

switch (MessageNum) { 
case MESSAGE1 : 

printf("Some immensely profound message\n"); 
break; 

case MESSAGE2 : 

printf("Some other immensely profound message\n"); 
break; 
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default : 
printf 

("Very trivial message, why not try MESSAGE1 or MESSAGE2?\n"); 
rc = EXIT_FAILURE; 

} 

} 

return rc; 


int main(void) 

{ 

return ErrorHandler(MESSAGEl, FATAL); 

/•kic-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-ki<-k-ki(-k-k-k-k-k-k 

The output should be: 

Fatal Error:Some immensely profound message 

■k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-klck-k-k-kick-k-k-k-k-k/ 

} 



Calling Conventions in the Programming Guide 
/Gp option in the User's Guide 
“<stdlib.h>” on page 816 
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perror — Print Error Message 

Format linclude <stdio.h> 

void perror(const char *string ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

perror prints an error message to stderr. If string is not NULL and does not point to 
a null character, the string pointed to by string is printed to the standard error 
stream, followed by a colon and a space. The message associated with the value in 
errno is then printed followed by a new-line character. 

To produce accurate results, you should ensure that perror is called immediately after 
a library function returns with an error; otherwise, subsequent calls may alter the 
errno value. 

Return Value There is no return value. 

This example tries to open a stream. If fopen fails, the example prints a message and 
ends the program. 

#inc1ude <stdio.h> 

#include <stdlib.h> 
int main(void) 

{ 

FILE *fh; 

if (NULL == (fh = fopen("myfile.mjq", "r"))) { 
perror("Could not open data file"); 
abort(); 

} 

return 0; 

/**************************************************************************** 

The output should be: 

Could not open data file: The file cannot be found. 
****************************************************************************/ 
i 

• “cl earerr — Reset Error Indicators.” on page 94 

• “terror — Test for Read/Write Errors” on page 223 

• “strerror — Set Pointer to Runtime Error Message” on page 579 

• “_strerror — Set Pointer to System Error String” on page 580 

• “<stdio.h>” on page 815 
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pow — Compute Power 

Format linclude <math.h> 

double pow(double x, double y); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

pow calculates the value of x to the power of y. 

Return Value Ify is 0, pow returns the value 1. If x is 0 and y is negative, pow sets errno to EDOM 

and returns 0. If both x and y are 0, or if x is negative and y is not an integer, pow 

sets errno to EDOM, and returns 0. 

If an overflow results, pow sets errno to ERANGE and returns +HUGE_VAL for a large 
result or -HUGE_VAL for a small result. 

This example calculates the value of 2 3 . 

linclude <stdio.h> 
linclude <math.h> 

int main(void) 

{ 

double x,y,z; 

x = 2.0; 
y = 3.0; 
z = pow(x, y); 

printf("%1f to the power of %lf is %lf\n", x, y, z); 
return 0; 

/•k-k-k'k-k-kle-k-k'k-k-kle-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k 

The output should be: 

2.000000 to the power of 3.000000 is 8.000000 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki< , k-k-k-k-k-k‘k-k-ki<-k-k‘J(-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k^ 

} 

• “exp — Calculate Exponential Function” on page 206 

• “_fsqrt — Calculate Square Root” on page 280 

• “1 og — Calculate Natural Logarithm” on page 387 

• “log 10 — Calculate Base 10 Logarithm” on page 388 

• “sqrt — Calculate Square Root” on page 556 

• “<math.h>” on page 811 
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printf — Print Formatted Characters 

Format linclude <stdio.h> 

int printf(const char *formot-string, argument-list); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

printf formats and prints a series of characters and values to the standard output 
stream stdout. The format-string consists of ordinary characters, escape 
sequences, and format specifications. The ordinary characters are copied in order of 
their appearance to stdout. Format specifications, beginning with a percent sign (%), 
determine the output format for any argument-list following the format-string. 

The format-string is read left to right. When the first format specification is 
found, the value of the first argument after the format-string is converted and 
output according to the format specification. The second format specification causes 
the second argument after the format-string to be converted and output, and so on 
through the end of the format-string. If there are more arguments than there are 
format specifications, the extra arguments are evaluated and ignored. The results are 
undefined if there are not enough arguments for all the format specifications. A 
format specification has the following form: 


^-flags-^ I— width—*' ^ - 1 


-precision- 



type —►*« 


Each field of the format specification is a single character or number signifying a 
particular format option. The type character, which appears after the last optional 
format field, determines whether the associated argument is interpreted as a character, 
a string, a number, or pointer. The simplest format specification contains only the 
percent sign and a type character (for example, %s). 
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The following optional fields control other aspects of the formatting: 


Field Description 

flags Justification of output and printing of signs, blanks, decimal points, 

octal, and hexadecimal prefixes, and the semantics for wchar_t 
precision unit. 

width Minimum number of characters (bytes) output. 

precision Maximum number of characters (bytes) printed for all or part of the 

output field, or minimum number of digits printed for integer values. 


h, 1, L 


Size of argument expected: 


h A prefix with the integer types d, i, o, u, x, X, and n that 

specifies that the argument is short int or unsigned short 
i nt. 

1 A prefix with d, i, o, u, x, X, and n types that specifies that the 

argument is a long int or unsigned long int. 

L A prefix with e, E, f, g, or G types that specifies that the 
argument is long double. 


Each field of the format specification is discussed in detail below. If a percent sign 
(%) is followed by a character that has no meaning as a format field, the character is 
simply copied to stdout. For example, to print a percent sign character, use %%. 


In extended mode, printf also converts floating-point values of NaN and infinity to 
the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 

If you specify a null string for the %s or %ls format specifier, printf prints (null). 
(In previous releases of C Set ++, printf produced no output for a null string.) 

The type characters and their meanings are given in the following table: 


Character 

Argument 

Output Format 

d, i 

Integer 

Signed decimal integer. 

u 

Integer 

Unsigned decimal integer. 

o 

Integer 

Unsigned octal integer. 

X 

Integer 

Unsigned hexadecimal integer, using abcdef. 

X 

Integer 

Unsigned hexadecimal integer, using ABCDEF. 
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Character 

Argument 

Output Format 

f 

Double 

Signed value having the form []dddd. dddd, where dddd is one or more 
decimal digits. The number of digits before the decimal point depends on 
the magnitude of the number. The number of digits after the decimal 
point is equal to the requested precision. NaN and infinity values are 
printed in lowercase (nan and infinity). 

F 

Double 

In extended mode (/Se option), identical to the f format except that NaN 
and infinity values are printed in uppercase (NAN and INFINITY). In modes 
other than extended, F is treated like any other character not included in 
this table. 

e 

Double 

Signed value having the form []d.dddde[sign]ddd, where d is a 
single-decimal digit, dddd is one or more decimal digits, ddd is 2 or 3 
decimal digits, and sign is + or -. 

E 

Double 

Identical to the e format except that E introduces the exponent instead of 

e. 

g 

Double 

Signed value printed in f or e format. The e format is used only when 
the exponent of the value is less than -4 or greater than precision. 
Trailing zeros are truncated, and the decimal point appears only if one or 
more digits follow it. 

G 

Double 

Identical to the g format except that E introduces the exponent (where 
appropriate) instead of e. 

c 

Character 

Single character. 

lc 

Wide character 

Multibyte character (converted as if by a call to wcrtomb). 

s 

String 

Characters printed up to the first null character (\0) or until precision is 
reached. If you specify a null string, (null) is printed. 

Is 

Wide-character 

string. 

Multibyte characters, printed up to the first wchar_t null character (L\0) is 
encountered in the wide-character string, or until the specified precision is 
reached. Conversion takes place as if by a call to wcrtomb. The 
displayed result does not include the terminating null character. If you do 
not specify the precision, you must end the wide-character string with a 
null character. A partial multibyte character cannot be written. If you 
specify a null string, (null) is printed. 

n 

Pointer to integer 

Number of characters successfully written so far to the stream or buffer; 
this value is stored in the integer whose address is given as the argument. 

p 

Pointer 

Pointer to void converted to a sequence of printable characters. 
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The flag characters and their meanings are as follows (notice that more than one 
flag can appear in a format specification): 


Table 3. Flag Characters 

Flag 

Meaning 

Default 

- 

Left-justify the result within the field 
width. 

Right-justify. 

+ 

Prefix the output value with a sign (+ or 
-) if the output value is of a signed type. 

Sign appears only for 
negative signed values (-). 

blankC ') 

Prefix the output value with a blank if the 
output value is signed and positive. The + 
flag overrides the blank flag if both 
appear, and a positive signed value will be 
output with a sign. 

No blank. 

# 

When used with the o, x, or X formats, the 
# flag prefixes any nonzero output value 
with 0, Ox, or OX, respectively. 

No prefix. 


When used with the f, F, e, or E formats, 
the # flag forces the output value to 
contain a decimal point in all cases. 

Decimal point appears only 
if digits follow it. 


When used with the g or G formats, the # 
flag forces the output value to contain a 
decimal point in all cases and prevents the 
truncation of trailing zeros. 

Decimal point appears only 
if digits follow it; trailing 
zeros are truncated. 


When used with the 1 s format, the # flag 
causes precision to be measured in wchar_t 
characters. 

Precision indicates the 
maximum number of bytes 
to be output. 

0 

When used with the d, i , o, it, x, X, e. E, 
f, F g, or G formats, the 0 flag causes 
leading 0's to pad the output to the field 
width. The 0 flag is ignored if precision is 
specified for an integer or if the - flag is 
specified. 

Space padding. 


The # flag should not be used with c, 1c, d, i, u, s, or p types. 

Width is a nonnegative decimal integer controlling the minimum number of characters 
printed. If the number of characters in the output value is less than the specified 
width , blanks are added on the left or the right (depending on whether the - flag is 
specified) until the minimum width is reached. 
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Width never causes a value to be truncated; if the number of characters in the output 
value is greater than the specified width, or width is not given, all characters of the 
value are printed (subject to the precision specification). 

For the 1 s type, width is specified in bytes. If the number of bytes in the output 
value is less than the specified width, single-byte blanks are added on the left or the 
right (depending on whether the - flag is specified) until the minimum width is 
reached. 

The width specification can be an asterisk (*), in which case an argument from the 
argument list supplies the value. The width argument must precede the value being 
formatted in the argument list. 

Precision is a nonnegative decimal integer preceded by a period, which specifies the 
number of characters to be printed or the number of decimal places. Unlike the 
width specification, the precision can cause truncation of the output value or 
rounding of a floating-point value. 

The precision specification can be an asterisk (*), in which case an argument from 
the argument list supplies the value. The precision argument must precede the 
value being formatted in the argument list. 


The interpretation of the precision value and the default when the precision is 
omitted depend upon the type, as shown in the following table; 


Type 

Meaning 

Default 

i 

d 

u 

0 

X 

X 

Precision specifies the minimum number of digits to be 
printed. If the number of digits in the argument is less than 
precision, the output value is padded on the left with zeros. 

The value is not truncated when the number of digits exceeds 
precision. 

If precision is 0 or omitted 
entirely, or if the period (.) 
appears without a number 
following it, the precision is 
set to 1. 

f 

Precision specifies the number of digits to be printed after the 

Default precision is six. If 

F 

decimal point. The last digit printed is rounded. 

precision is 0 or the period 

e 


appears without a number 

E 


following it, no decimal point 
is printed. 

g 

Precision specifies the maximum number of significant digits 

All significant digits are 

G 

printed. 

printed. 

c 

No effect. 

The character is printed. 

lc 

No effect. 

The wchar_t character is 
printed. 
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Type 

Meaning 

Default 

S 

Precision specifies the maximum number of characters to be 
printed. Characters in excess of precision are not printed. 

Characters are printed until a 
null character is encountered. 

Is 

Precision specifies the maximum number of bytes to be 
printed. Bytes in excess of precision are not printed; 
however, multibyte integrity is always preserved. 

wchar_t characters are printed 
until a null character is 

encountered. 


Return Value The printf function returns the number of bytes printed. 

This example prints data in a variety of formats, 

linclude <stdio.h> 

int main(void) 

{ 

char ch = 'h',*string = "computer"; 
int count = 234,hex = 0x10,oct = 010,dec = 10; 
double fp = 251.7366; 

printf("%d %+d %06d %X %x %o\n\n", count, count, count, count 

, count, count); 

printf("1234567890123%n4567890123456789\n\n", &count); 
printf("Value of count should be 13; count = %d\n\n", count); 
printf("%10c%5c\n\n", ch, ch); 
printf("%25s\n%25.4s\n\n", string, string); 
printf("%f %.2f %e %E\n\n", fp, fp, fp, fp); 

printf("%i %i %i\n\n", hex, oct, dec); 
return 0; 

/**************************************************************************** 

The output should be: 

234 +234 000234 EA ea 352 

12345678901234567890123456789 
Value of count should be 13; count = 13 
h h 

computer 
comp 

251.736600 251.74 2.517366e+02 2.517366E+02 

16 8 10 

****************************************************************************/ 

} 
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• “_cprintf — Print Characters to Screen” on page 113 

• “fpri ntf — Write Formatted Data to a Stream” on page 249 

• “fscanf — Read Formatted Data” on page 271 

• “scanf — Read Data” on page 517 

• “spri ntf — Print Formatted Data to Buffer” on page 554 

• “sscanf — Read Data” on page 559 

• “swprintf — Format and Write Wide Characters to Buffer” on page 635 

• “vfprintf — Print Argument Data to Stream” on page 739 

• “vpri ntf — Print Argument Data” on page 741 

• “vsprintf — Print Argument Data to Buffer” on page 743 

• “vswprintf — Format and Write Wide Characters to Buffer” on page 745 

• “<stdio.h>” on page 815 
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putc - putchar — Write a Character 

Format linclude <stdio.h> 

int putc(int c, FILE *stream ); 
int putchar(int c); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

putc converts c to unsigned char and then writes c to the output stream at the 
current position, putchar is equivalent to putc (c, stdout). 

putc is equivalent to fputc except that, if it is implemented as a macro, putc can 
evaluate stream more than once. Therefore, the stream argument to putc should not 
be an expression with side effects. 

Return Value putc and putchar return the character written. A return value of EOF indicates an 
error. 

This example writes the contents of a buffer to a data stream. In this example, the 
body of the for statement is null because the example carries out the writing 
operation in the test expression, 
linclude <stdio.h> 

Idefine LENGTH 80 

int main(void) 

{ 

FILE *stream = stdout; 
int i,ch; 

char buffer[LENGTH+l] = "Hello world"; 

/* This could be replaced by using the fwrite routine */ 

for (i =0; (i < sizeof(buffer)) && ((ch = putc(buffer[i], stream)) != EOF); 

++i) 

return 0; 

/•k-k-kle-k-kle-k-k'k-k-k'k-k-kle-k-kle-k-k'k'k-k'k-k-kle-k-kle-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k 

The output should be: 

Hello world 

■k-k-k-klc-k-kle-k-k'k-k-kle-k-klc-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-kick-k'k/ 

} 

• “fputc — Write Character” on page 252 

• “_fputchar — Write Character” on page 254 

• “fwri te — Write Items” on page 289 

• “getc - getchar — Read a Character” on page 296 

• “_putch — Write Character to Screen” on page 470 
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“puts — Write a String” on page 473 

“wri te — Writes from Buffer to File” on page 799 

“<stdio.h>” on page 815 
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putch — Write Character to Screen 

Format linclude <conio.h> 

int _putch(int c); 

Description Language Level: Extension 

_putch writes the character c directly to the screen. 


Return Value If successful, _putch returns c. If an error occurs, _putch returns EOF. 



This example defines a function gchar that is similar to _getche using the _putch 
and _getch functions: 

#include <conio.h> 


int gchar(void) 

{ 

int ch; 


ch = _getch(); 
_putch(ch); 
return (ch); 



“_cputs — Write String to Screen” on page 114 
“_cpri ntf — Print Characters to Screen” on page 113 
“fputc — Write Character” on page 252 

“_getch - _getche — Read Character from Keyboard” on page 298 

“putc - putchar — Write a Character” on page 468 

“puts — Write a String” on page 473 

“wri te — Writes from Buffer to File” on page 799 

“<conio.h>” on page 802 
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putenv — 

Format 

Description 


Modify Environment Variables 

linclude <stdlib.h> 

int putenv(char *envstring ); 

Language Level: XPG4, Extension 

putenv adds new environment variables or modifies the values of existing 
environment variables. Environment variables define the environment in which a 
process runs (for example, the default search path for libraries to be linked with a 
program). 

The envstring argument must be a pointer to a string with the form: 
varname=string 

where varname is the name of the environment variable to be added or modified and 
string is the value of the variable. See the Notes below. 

If varname is already part of the environment, string replaces its current value; if 
not, the new varname is added to the environment with the value string. To set a 
variable to an empty value, specify an empty string. A variable can be removed 
from the environment by specifying varname only, for example: 

putenv("PATH"); 

Do not free the env string pointer while the entry it points to is in use, or the 
environment variable will point into freed space. A similar problem can occur if you 
pass a pointer to a local variable to putenv and then exit from the function in which 
the variable is declared. Once you have added the envstring with putenv, any 
change to the entry it points to changes the environment used by your program. 

The environment manipulated by putenv is local to the process currently running. 
You cannot enter new items in your command-level environment using putenv. 

When the program ends, the environment reverts to the parent process environment. 
This environment is passed on to some child processes created by the _spawn, exec, 
or system functions, and they get any new environment variables added using 
putenv. 

DosScanEnv will not reflect any changes made using putenv, but getenv will reflect 
the changes. 
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Notes: 

1. putenv can change the value of _environ, thus invalidating the envp argument to 
the main function. 

2. You cannot use %envvar %, where envvar is any OS/2 environment variable, 
with putenv to concatenate new envstring and old envstring. 

3. In earlier releases of C Set ++, putenv began with an underscore (_putenv). 
Because it is defined by the X/Open standard, the underscore has been removed. 
For compatibility, VisualAge C++ will map _putenv to putenv for you. 


Return Value putenv returns 0 if it is successful. A return value of -1 indicates an error. 



This example tries to change the environment variable PATH, and then uses getenv 
to get the current path. If the call to putenv fails, the example writes an error 
message. 

#include <stdlib.h> 

#include <stdio.h> 


int main(void) 

{ 

char *pathvar; 

if (-1 == putenv("PATH=a:\\bin;b:\\andy")) { 
printf("putenv failed - out of memory\n"); 
return EXIT_FAILURE; 

} 



/* getting and printing the current environment path */ 

pathvar = getenv("PATH"); 

printf("The current path is: %s\n", pathvar); 

return 0; 

/■k-k-klc-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-kit'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k 

The output should be: 

The current path is: a:\bin;b:\andy 

■k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-ki(-k-k‘k-k-k‘k-k-k‘k-k-k‘J(-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-kick-k^ 

} 

• “execl - _execvpe — Load and Run Child Process” on page 200 

• “getenv — Search for Environment Variables” on page 305 

• “_spawnl - _spawnvpe — Start and Run Child Processes” on page 548 

• “system — Invoke the Command Processor” on page 639 

• “envp Parameter to main” in the Programming Guide 

• “<stdlib.h>” on page 816 
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puts — Write a String 

Format linclude <stdio.h> 

int puts(const char *string ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

puts writes the given string to the standard output stream stdout; it also appends a 
new-line character to the output. The terminating null character is not written. 

Return Value puts returns EOF if an error occurs. A nonnegative return value indicates that no 
error has occurred. 

This example writes Hello World to stdout. 

#inc1ude <stdio.h> 

int main(void) 

{ 

if (EOF == puts("Hello World")) 
printf("Error in puts\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

Hello World 

****************************************************************************/ 

i 

• “_cputs—Write String to Screen” on page 114 

• “fputs — Write String” on page 255 

• “gets — Read a Line” on page 309 

• “putc - putchar — Write a Character” on page 468 

• “<stdio.h>” on page 815 




Chapter 3. Library Functions 473 




putwc 


putwc — Write Wide Character 

Format #include <stdio.h> 

linclude <wchar.h> 

wint_t putwc(wint_t wc, FILE ^stream ); 

Description Language Level: ANSI 93, XPG4 

putwc converts the wide character wc to a multibyte character, and writes it to the 
stream at the current position. It also advances the file position indicator for the 
stream appropriately. 

putwc function is equivalent to fputwc except that, if it is implemented as a macro, 
putwc can evaluate stream more than once. Therefore, the stream argument to 
putwc should not be an expression with side effects. 

The behavior of putwc is affected by the LC_CTYPE category of the current locale. 
Using a non-wide-character function with putwc on the same stream results in 
undefined behavior. 

After calling putwc, flush the buffer or reposition the stream pointer before calling a 
write function for the stream, unless EOF has been reached. After a write operation 
on the stream, flush the buffer or reposition the stream pointer before calling putwc. 


Return Value putwc returns the wide character written. If a write error occurs, putwc sets the 

error indicator for the stream and returns WEOF. If an encoding error occurs when a 
wide character is converted to a multibyte character, putwc sets errno to EILSEQ and 
returns WEOF. 



The following example uses putwc to convert the wide characters in wcs to multibyte 
characters and write them to the file putwc.out. 

#include <stdio.h> 

#include <wchar.h> 

#include <stdlib.h> 

#include <errno.h> 


int main(void) 

{ 

FILE *stream; 

wchar_t *wcs = L"A character string."; 
int i; 
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if (NULL == (stream = fopen("putwc.out", "w"))) { 
printf("Unable to open: \"putwc.ojt\".\n"); 
exit(EXIT_FAILURE); 


for (i = 0; wcs[i] != L'\0'; i++) { 
errno = 0; 

if (WEOF == putwc(wcs[i], stream)) { 

printf("Unable to putwc() the wide character.\n" 

"wcs[%d] = 0x%lx\n", i, wcs[i]); 
if (EILSEQ == errno) 

printf("An invalid wide character was encountered.\n"); 
exit(EXITFAILURE); 

} 


fclose(stream); 
return 0; 

/**************************************************************************** 
The output file putwc.out should contain : 

A character string. 

****************************************************************************/ 


• “fputc — Write Character” on page 252 

• “_fputchar — Write Character” on page 254 

• “fputwc — Write Wide Character” on page 257 

• “getwc — Read Wide Character from Stream” on page 315 

• “putc - putchar — Write a Character” on page 468 

• “_putch — Write Character to Screen” on page 470 

• “putwchar — Write Wide Character to stdout” on page 476 

• “<stdio.h>” on page 815 

• “<wchar.h>” on page 821 
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putwchar — 

Format 

Description 


Return Value 



Write Wide Character to stdout 

linclude <wchar.h> 
wint_t putwchar(wint_t wc); 

Language Level: ANSI 93, XPG4 

putwchar converts the wide character wc to a multibyte character and writes it to 
stdout. A call to putwchar is equivalent to putwc(wc, stdout). 

The behavior of putwchar is affected by the LC_CTYPE category of the current 
locale. Using a non-wide-character function with putwchar on the same stream 
results in undefined behavior. 

After calling putwchar, flush the buffer or reposition the stream pointer before calling 
a write function for the stream, unless EOF has been reached. After a write operation 
on the stream, flush the buffer or reposition the stream pointer before calling 
putwchar. 

putwchar returns the wide character written. If a write error occurs, putwchar sets 
the error indicator for the stream and returns WEOF. If an encoding error occurs 
when a wide character is converted to a multibyte character, putwchar sets errno to 
EILSEQ and returns WEOF. 

This example uses putwchar to write the string in wcs. 

#include <stdio.h> 

#include <wchar.h> 

#include <errno.h> 

#include <stdlib.h> 

int main(void) 

{ 

wchar_t *wcs = L"A character string."; 
int i; 

for (i = 0; wcs[i] != L 1 \0 1 ; i++) { 
errno = 0; 
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if (WEOF == putwchar(wcs[i])) { 

printf("Unable to putwchar() the wide character.\n"); 
printf("wcs[%d] = Ox%lx\n", i, wcs[i]); 
if (EILSEQ == errno) 

printf("An invalid wide character was encountered.\n"); 
exit(EXIT_FAILURE); 

} 


return 0; 

/**************************************************************************** 
The output should be similar to : 

A character string. 

****************************************************************************/ 


• “fputc — Write Character” on page 252 

• “_fputchar — Write Character” on page 254 

• “fputwc — Write Wide Character” on page 257 

• “getwchar — Get Wide Character from stdin” on page 317 

• “putc - putchar — Write a Character” on page 468 

• “_putch — Write Character to Screen” on page 470 

• “<wchar.h>” on page 821 
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qsort — Sort Array 

Format linclude <stdlib.h> 

void qsort(void *base, size_t num, size_t width, 

int(*compore)(const void *key, const void *element )); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

qsort sorts an array of num elements, each of width bytes in size. The base pointer 
is a pointer to the array to be sorted, qsort overwrites this array with the sorted 
elements. 


The compare argument is a pointer to a function you must supply that takes a pointer 
to the key argument and to an array element, in that order, qsort calls this function 
one or more times during the search. The function must compare the key and the 
element and return one of the following values: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

key less than element 
key equal to element 
key greater than element 


The sorted array elements are stored in ascending order, as defined by your compare 
function. You can sort in reverse order by reversing the sense of “greater than” and 
“less than” in compare. The order of the elements is unspecified when two elements 
compare equally. 


Return Value There is no return value. 
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This example sorts the arguments (argv) in ascending lexical sequence, using the 
comparison function compare() supplied in the example. 

#include <stdio.h> 

#inc1ude <stdlib.h> 

#include <string.h> 


/* - */ 

/* compared routine called internally by qsort() */ 
/* */ 
/* Assert: Library always calls functions internally with */ 
/* _0ptlink linkage convention. Ensure that compared is */ 
/* always _0pt1 ink. */ 
/* -- */ 


int _0ptlink compare(const void *argl,const void *arg2) 

{ 

return (strcmp(*(char **)argl, *(char **)arg2)); 

} 


int main(int argc,char *argv[]) 

{ 

i nt i; 

argv++; 

argc--; 

qsort((char *)argv, argc, sizeof(char *), compare); 
for (i = 0; i < argc; ++i) 
printf("%s\n", argv[i]); 
return 0; 

/**************************************************************************** 
Assuming command line of: qsort kent theresa andrea laura brenden 
Output should be: 

andrea 
brenden 
kent 
1 aura 
theresa 

****************************************************************************/ 


• “bsearch — Search Arrays” on page 76 

• “1 fi nd - 1 search — Find Key in Array” on page 374 

• “<search.h>” on page 813 

• “<stdlib.h>” on page 816 
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raise — Send Signal 

Format linclude <signal.h> 

int raise(int sic?); 


Description Language Level: ANSI, SAA, XPG4 

raise sends the signal sig to the running program. You can then use signal to 
handle sig. 

Signals and signal handling are described in “signal — Handle Interrupt Signals” on 
page 540, and in the Programming Guide under Signal and Exception Handling. 


Return Value rai se returns 0 if successful, nonzero if unsuccessful. 



This example establishes a signal handler called sig_hand for the signal SIGUSR1. 
The signal handler is called whenever the SIGUSR1 signal is raised and will ignore 
the first nine occurrences of the signal. On the tenth raised signal, it exits the 
program with an error code of 10. Note that the signal handler must be reestablished 
each time it is called. 

#include <signal.h> 

#include <stdio.h> 


void sig_hand(int); /* declaration of sig_hand() as a function */ 

int main(void) 

{ 

signal(SIGUSR1, sig_hand); /* set up handler for SIGUSR1 */ 

raise(SIGUSR1); /* signal SIGUSR1 is raised */ 

/* sig_hand() is called */ 

return 0; 


void sig_hand(int sig) 

{ 

static int count = 0; /* initialized only once */ 

count++; 

if (10 == count) /* ignore the first 9 occurrences of this signal */ 
exit(10); 
else 

signal(SIGUSR1, sig hand); /* set up the handler again */ 

raise(SIGUSRl); 



“signal — Handle Interrupt Signals” on page 540 
Signal and Exception Handling in the Programming Guide 
“<signal.h>” on page 814 
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rand — Generate Random Number 


Format linclude <stdlib.h> 

int rand(void); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

rand generates a pseudo-random integer in the range 0 to RAND_MAX (macro defined in 
<stdlib.h>). Use srand before calling rand to set a starting point for the random 
number generator. If you do not call srand first, the default seed is 1. 


Return Value rand returns a pseudo-random number. 



This example prints the first 10 random numbers generated. 

#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

i nt x; 


for (x = 1; x <= 10; x++) 

printf("iteration %d, rand=%d\n", x, rand()); 
return 0; 


/**************************************************************************** 
The output should be: 

iteration 1, rand=16838 
iteration 2, rand=5758 
iteration 3, rand=10113 
iteration 4, rand=17515 
iteration 5, rand=31051 
iteration 6, rand=5627 
iteration 7, rand=23010 
iteration 8, rand=7419 
iteration 9, rand=16212 
iteration 10, rand=4086 

****************************************************************************/ 

} 



“srand — Set Seed for rand Function” on page 557 
“<stdlib.h>” on page 816 
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read — Read Into Buffer 

Format linclude <io.h> 

int read(int handle, char *buffer, unsigned int count)-. 

Description Language Level: XPG4, Extension 

read reads count bytes from the file associated with handle into buffer. The read 
operation begins at the current position of the file pointer associated with the given 
file. After the read operation, the file pointer points to the next unread character. 

Note: In earlier releases of C Set ++, read began with an underscore (_read). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _read to read for you. 

Return Value read returns the number of bytes placed in buffer. This number can be less than 

count if there are fewer than count bytes left in the file or if the file was opened in 
text mode. (See the note below.) The return value 0 indicates an attempt to read at 
end-of-file. A return value -1 indicates an error. If -1 is returned, the current file 
position is undefined, and errno is set to one of the following values: 

Value Meaning 

EBADF The given handle is incorrect, or the file is not open for reading, or 

the file is locked. 

EOS2ERR The call to the operating system was not successful. 

Note: If the file was opened in text mode, the return value might not correspond to 
the number of bytes actually read. When text mode is in effect, carriage return 
characters are deleted from the input stream without affecting the file pointer. 

This example opens the file sample.dat and attempts to read from it. 

linclude <io.h> 
linclude <stdio.h> 
linclude <stdlib.h> 
linclude <fcntl.h> 
linclude <string.h> 
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int main(void) 

{ 

int fh; 

char buffer[20]; 


memset(buffer, '\0', 20); 
printf("\nCreating sample.dat.\n"); 
system("echo Sample Program > sample.dat"); 
if (-1 == (fh = open("sample.dat", 0_RDWR|0_APPEND))) { 
perror("Unable to open sample.dat."); 
return EXIT_FAILURE; 

} 

if (7 != read(fh, buffer, 7)) { 

perror("Unable to read from sample.dat."); 
close(fh); 

return EXIT_FAILURE; 


printf("Successfully read in the following:\n%s\n ", buffer); 
close(fh); 
return 0; 


/**************************************************************************** 
The output should be: 

Creating sample.dat. 

Successfully read in the following: 

Sample 

****************************************************************************/ 

} 



“creat — Create New File” on page 115 

“fread — Read Items” on page 261 

“open — Open File” on page 447 

“_Sopen — Open Shared File” on page 545 

“wri te — Writes from Buffer to File” on page 799 
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realloc — Change Reserved Storage Block Size 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void *realloc(void *ptr, size_t size); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

real loc changes the size of a previously reserved storage block. The ptr argument 
points to the beginning of the block. The size argument gives the new size of the 
block, in bytes. The contents of the block are unchanged up to the shorter of the new 
and old sizes, real loc allocates the new block from the same heap the original 
block was in. 

If ptr is NULL, real 1 oc reserves a block of storage of size bytes from the current 
thread's default heap (equivalent to calling malloc(szze)). 

If size is 0 and the ptr is not NULL, real loc frees the storage allocated to ptr and 
returns NULL 


Return Value real loc returns a pointer to the reallocated storage block. The storage location of 

the block may be moved by the realloc function. Thus, the ptr argument to realloc 
is not necessarily the same as the return value. 

If size is 0, real loc returns NULL. If there is not enough storage to expand the block 
to the given size, the original block is unchanged and real loc returns NULL. 

The storage to which the return value points is aligned for storage of any type of 
object. 



This example allocates storage for the prompted size of array and then uses real loc 
to reallocate the block to hold the new size of the array. The contents of the array 
are printed after each allocation. 
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#include <stdio.h> 
#include <stdlib.h> 


int main(void) 

{ 

long *array; 
long *ptr; 
i nt i; 

int numl,num2; 

void print_array(long *ptr_array. 


/* start of the array */ 

/* pointer to array */ 

/* index variable */ 

/* number of entries of the array */ 
int size); 


printf("Enter the size of the array\n"); 
scanf("%i", &numl); 


/* allocate numl entries using malloc() */ 

if ((array = malloc(numl *sizeof(long))) != NULL) { 

for (ptr = array, i = 0; i < numl; ++i) /* assign values */ 

*ptr++ = i; 

print_array(array, numl); 
printf("\n"); 

} 

else { /* malloc error */ 

perror("0ut of storage"); 
abort(); 


/* Change the size of the array ... */ 

printf("Enter the size of the new array\n"); 

scant("%i", &num2); 

if ((array = real 1oc(array, num2 *sizeof(long))) != NULL) { 
for (ptr = array+numl, i = numl; i <= num2; ++i) 

*ptr++ = i+2000; /* assign values to new elements */ 

print_array(array, num2); 

} 

else { /* realloc error */ 

perror("0ut of storage"); 
abort(); 


return 0; 


/**************************************************************************** 
The output should be similar to: 


Enter the size of the array 
2 

The array of size 2 is: 
array[ 0 ] = 0 
array[ 1 ] = 1 

Enter the size of the new array 
4 
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The array of size 4 is: 
array[ 0 ] = 0 

array[ 1 ] = 1 

array[ 2 ] = 2002 

array[ 3 ] = 2003 

*********************************************************■****'**'*'**'***'***'*'**'*/ 

} 


void print_array(long *ptr_array,int size) 

{ 

i nt i; 

long *index = ptr_array; 

printf("The array of size %d is:\n", size); 

for (i = 0; i < size; ++i) /* print the array 

out */ 

printf(" array[ %i ] = %li\n", i, ptr_array[i]); 



“cal loc — Reserve and Initialize Storage” on page 80 

“_debug_real 1 oc — Reallocate Memory Block” on page 147 

“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 

“free — Release Storage Blocks” on page 263 

“mal loc — Reserve Storage Block” on page 403 

“_msi ze — Return Number of Bytes Allocated” on page 441 

“_treal 1 oc — Reallocate Tiled Storage Block” on page 679 

“<malloc.h>” on page 810 

“<stdlib.h>” on page 816 
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regcomp — Compile Regular Expression 

Format linclude <regex.h> 

int regcomp(regex_t *preg, const char *pattern, int cflags ); 

Description Language Level: POSIX, XPG4 

regcomp compiles the source regular expression pointed to by pattern into an 
executable version and stores it in the location pointed to by preg. You can then use 
regexec to compare the regular expression to other strings. 

The cflags flag defines the attributes of the compilation process: 

REG_EXTENDED 

Support extended regular expressions. 

REG_NEWLINE 

Treat new-line character as a special end-of-line character; it then establishes 
the line boundaries matched by the ^ and $ patterns, and can only be matched 
within a string explicitly using \n. (If you omit this flag, the new-line character 
is treated like any other character.) 

REG_ICASE 

Ignore case in match. 

REG_NOSUB 

Ignore the number of subexpressions specified in pattern. When you compare 
a string to the compiled pattern (using regexec), the string must match the 
entire pattern, regexec then returns a value that indicates only if a match was 
found; it does not indicate at what point in the string the match begins, or what 
the matching string is. 

Regular expressions are a context-independent syntax that can represent a wide 
variety of character sets and character set orderings, which can be interpreted 
differently depending on the current locale. The functions regcomp, regerror, 
regexec, and regfree use regular expressions in a similar way to the UNIX awk, ed, 
grep, and egrep commands. Regular expressions are described in more detail under 
“Regular Expressions” in the Programming Guide. 

Return Value If regcomp is successful, it returns 0. Otherwise, it returns an error code that you 
can use in a call to regerror, and the content of preg is undefined. 
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This example compiles an extended regular expression. 

#include <regex.h> 

#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

regex_t preg; 

char *pattern = ".*(simple).*"; 

int rc; 

if (0 != (rc = regcomp(&preg, pattern, REG_EXTENDED))) { 
printf("regcompO failed, returning nonzero (%d)\n", rc); 
exit(EXIT_FAILURE); 

} 

printf ("regcompO is sucessful An"); 
return 0; 


The output should be similar to : 
regcompO is sucessful. 

■klt-k-k-k-k-kie-k-k-k-k-k-k-k-k'k-k-kic-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-kie'k-k-k-k-k-k-k-k-k-k-k-kie-k-k-k-k-k-k-kick-k-kick-k'k-k-klck-k/ 

} 



“regerror — Return Error Message for Regular Expression” on page 489 
“regexec — Execute Compiled Regular Expression” on page 491 
“regfree — Free Memory for Regular Expression” on page 494 
“Regular Expressions” in the Programming Guide 
“<regex.h>” on page 813 
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regerror — 

Format 

Description 


Return Value 


Return Error Message for Regular Expression 

linclude <regex.h> 

size_t regerror(int errcode, const regex_t *preg, 
char *errbuf, size_t errbuf_size ); 


Language Level: POSIX, XPG4 

regerror finds the description for the error code errcode for the regular expression 
preg. The description for errcode is assigned to errbuf. errbuf_size is a value 
that you provide that specifies the maximum message size that can be stored (the size 
of errbuf). 


Regular expressions are described in detail under “Regular Expressions” in the 
Programming Guide. 


The description strings for errcode are: 


errcode 

REG_NOMATCH 

REG_BADPAT 

REG_ECOLLATE 

REG_ECTYPE 

REG_EESCAPE 

REG_ESUBREG 

REG_EBRACK 

REG_EPAREN 

REG_EBRACE 

REG_BADBR 

REG_ERANGE 

REG_ESPACE 

REG_BADRPT 

REG_ECHAR 

REG_EBOL 

REG_EEOL 


Description String 

RE pattern not found 
Invalid regular expression 
Invalid collating element 
Invalid character class 
Last character is \ 

Invalid number in \digit 

[] imbalance 

\( \) or () imbalance 

\ { \} or { } imbalance 

Invalid \{ \} range exp 

Invalid range exp endpoint 

Out of memory 

?*+ not preceded by valid RE 

Invalid multibyte character 

^ anchor and not BOL 

$ anchor and not EOL 


The error descriptions are in the IBMCRERR.MSG message file. The directory for 
this file must be in your DPATH environment variable for the messages to be found. 


regerror returns the size of the buffer needed to hold the string that describes the 
error condition. 
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This example compiles an invalid regular expression, and prints an error message 
using regerror. 


#include <regex.h> 
#include <stdio.h> 

#include <stdlib.h> 


int main(void) 

{ 

regex_t preg; 

char *pattern = "a[missing.bracket"; 

int rc; 

char buffer[100]; 

if (0 != (rc = regcomp(&preg, pattern, REG_EXTENDED))) { 
regerror(rc, &preg, buffer, 100); 
printf("regcompO failed with '%s'\n“, buffer); 
exit(EXIT_FAILURE); 

} 

return 0; 

/ ‘k-k-kle-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k'k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k 

The output should be similar to : 
regcompO failed with 1 [] imbalance 1 

ie*ic-k‘k-k-k‘k-k-k‘k-k-k‘k-k1< , k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k/ 

} 



“regcomp — Compile Regular Expression” on page 487 
“regexec — Execute Compiled Regular Expression” on page 491 
“regfree — Free Memory for Regular Expression” on page 494 
“Regular Expressions” in the Programming Guide 
“<regex.h>” on page 813 
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regexec — 

Format 

Description 


Execute Compiled Regular Expression 

linclude <regex.h> 

int regexec(const regex_t *preg, const char * string, 

size_t nmatch, regmatch_t *pmatch, int eflags); 

Language Level: POSIX, XPG4 

regexec compares the null-terminated string against the compiled regular 
expression preg to find a match between the two. (Regular expressions are described 
in “Regular Expressions” in the Programming Guide.) 

nmatch is the number of substrings in string that regexec should try to match with 
subexpressions in preg. The array you supply for pmatch must have at least nmatch 
elements. 

regexec fills in the elements of the array pmatch with offsets of the substrings in 
string that correspond to the parenthesized subexpressions of the original pattern 
given to regcomp to create preg. The zeroth element of the array corresponds to the 
entire pattern. If there are more than nmatch subexpressions, only the first nmatch - 
1 are stored. If nmatch is 0, or if the REG_NOSUB flag was set when preg was 
created with regcomp, regexec ignores the pmatch argument. 

The eflags flag defines customizable behavior of regexec: 

REG_NOTBOL 

Indicates that the first character of string is not the beginning of line. 
REG_NOTEOL 

Indicates that the first character of string is not the end of line. 

When a basic or extended regular expression is matched, any given parenthesized 
subexpression of the original pattern could participate in the match of several 
different substrings of string. The following rules determine which substrings are 
reported in pmatch.: 

1. If a subexpression participated in a match several times, regexec stores the offset 
of the last matching substring in pmatch. 

2. If a subexpression did not match in the source string, regexec sets the offset 
shown in pmatch to -1. 

3. If a subexpression contains subexpressions, the data in pmatch refers to the last 
such subexpression. 

4. If a subexpression matches a zero-length string, the offsets in pmatch refer to the 
byte immediately following the matching string. 
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Return Value 



If the REG_NOSUB flag was set when preg was created by regcomp, the contents of 
pmatch are unspecified. If the REG_NEWLINE flag was not set when preg was 
created, new-line characters are allowed in string. 

Note: If MB_CUR_MAX is specified as 2, the charmap file does not specify the 
DBCS characters, and a collating element (for example, [: a: ]) is specified in the 
pattern, the DBCS characters will not match against the collating-element even if they 
have an equivalent weight to the collating-element. 


If a match is found, regexec returns 0. Otherwise, it returns a nonzero value 
indicating either no match or an error. 

This example compiles an expression and matches a string against it. The first 
substring uses the full pattern. The second substring uses the sub-expression inside 
the full pattern. 

#include <regex.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

regex_t preg; 

char *string = "a very simple simple simple string"; 

char *pattern = "\\(sim[a-z]1e\\) \\1"; 

int rc; 

size_t nmatch = 2; 

regmatch_t pmatch[2]; 

if (0 != (rc = regcomp(&preg, pattern, 0))) { 

printf ("regcompO failed, returning nonzero (%d)\n", rc); 
exit(EXIT_FAILURE); 

} 


if (0 != (rc = regexec(&preg, string, nmatch, pmatch, 0))) { 
printf("Failed to match 1 %s' with '%s 1 .returning %d.\n", 
string, pattern, rc); 

} 

else { 

printf("With the whole expression, " 

"a matched substring \"%.*s\" is found at position %d to %d.\n", 
pmatch[0].rm_eo - pmatch[0].rm_so, &string[pmatch[0].rm_so], 
pmatch[0].rm_so, pmatch[0].rm_eo - 1); 
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printf("With the sub-expression, " 

"a matched substring \"%.*s\" is found at position %d to %d.\n", 
pmatch[l].rm_eo - pmatch[l].rm_so, &string[pmatch[l].rm_so], 
pmatch[l].rm_so, pmatch[l].rm_eo - 1); 

} 

regfree(&preg); 

return 0; 

/**************************************************************************** 
The output should be similar to : 

With the whole expression, a matched substring "simple simple" is found 
at position 7 to 19. 

With the sub-expression, a matched substring "simple" is found 
at position 7 to 12. 

****************************************************************************/ 


• “regcomp — Compile Regular Expression” on page 487 

• “regerror — Return Error Message for Regular Expression” on page 489 

• “regfree — Free Memory for Regular Expression” on page 494 

• “Regular Expressions” in the Programming Guide 

• “<regex.h>” on page 813 
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regfree — Free Memory for Regular Expression 

Format linclude <regex.h> 

void regfree(regex_t *preg); 

Description Language Level: POSIX, XPG4 

regfree frees any memory that was allocated by regcomp to implement the regular 
expression preg. After the call to regfree, the expression defined by preg is no 
longer a compiled regular or extended expression. 

Regular expressions are described in “Regular Expressions” in the Programming 
Guide. 


Return Value There is no return value. 

This example compiles an extended regular expression and frees it. 

linclude <regex.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

regex_t preg; 

char *pattern = ".*(simple); 

int rc; 

if (0 != (rc = regcomp(&preg, pattern, REG_EXTENDED))) { 
printf ("regcompO failed, returning nonzero (%d)\n", rc); 
exit(EXIT_FAILURE); 

} 

regfree(&preg); 

printf("Memory allocated for reg is freed.\n"); 
return 0; 

/•k-k-kic-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k'k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-kick-k-kick-k-k-k-k-k-k-k-kidck-k-k-k 

The output should be similar to : 

Memory allocated for reg is freed. 

**********************************************************************■**■****/ 

} 




“regcomp — Compile Regular Expression” on page 487 

“regerror — Return Error Message for Regular Expression” on page 489 

“regexec — Execute Compiled Regular Expression” on page 491 

“Regular Expressions” in the Programming Guide 

“<regex.h>” on page 813 
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remove — Delete File 

Format linclude <stdio.h> 

int remove(const char *filename); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

remove deletes the file specified by fi lermme. 

Note: You cannot remove a nonexistent file or a file that is open. 

Return Value remove returns 0 if it successfully deletes the file. A nonzero return value idicates 
an error. 

This example uses remove to remove a file. It issues a message if an error occurs. 

#include <stdio.h> 

int main(void) 

{ 

char *FileName = "fi1e2rm.mjq"; 

FILE *fp; 

fp = fopen(FileName, "w"); 
fprintf(fp, "Hel1o world\n"); 
fclose(fp); 

if (remove(Fi1eName) != 0) 

perror("Could not remove file"); 
el se 

printf("File \"%s\" removed successfully.\n", FileName); 
return 0; 

/**************************************************************************** 

The output should be: 

File "file2rm.mjq" removed successfully. 
****************************************************************************/ 

} 

• “fopen — Open Files” on page 243 

• “rename — Rename File” on page 496 

• “_rmtmp — Remove Temporary Files” on page 513 

• “uni ink — Delete File” on page 729 

• “<stdio.h>” on page 815 
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rename — Rename File 

Format linclude <stdio.h> /* also in <io.h> */ 

int rename(const char *oldname, const char *newname); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

rename renames the file specified by oldname to the name given by newname. The 
oldname pointer must specify the name of an existing file. The newname pointer must 
not specify the name of an existing file. Both oldname and newname must be on the 
same drive; you cannot rename files across drives. You cannot rename a file with the 
name of an existing file. You also cannot rename an open file. 

Return Value rename returns 0 if successful. On an error, it returns a nonzero value. 

This example uses rename to rename a file. It issues a message if errors occur, 
linclude <stdio.h> 

int main(void) 

{ 

char *01dName = "oldfile.mjq"; 
char *NewName = "newfile.mjq"; 

FILE *fp; 

fp = fopen(01dName, "w"); 
fprintf(fp, "Hel1o world\n"); 
fclose(fp); 

if (rename(01dName, NewName) != 0) 
perror("Could not rename file"); 
else 

printf("File \“%s\" is renamed to \"%s\".\n", OldName, NewName); 
return 0; 

/*********************************************■**************■***'*'**'*'**'***'*'**'** 

The output should be: 

File "oldfile.mjq" is renamed to "newfi1e.mjq". 

i 

• “fopen — Open Files” on page 243 

• “remove — Delete File” on page 495 

• “<stdio.h>” on page 815 
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rewind — Adjust Current File Position 

Format linclude <stdio.h> 

void rewind(FILE *stream ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

rewind repositions the file pointer associated with stream to the beginning of the file. 
A call to rewi nd is the same as: 

(void)fseek(streom, 0L, SEEK_SET); 

except that rewind also clears the error indicator for the stream. 


Return Value There is no return value. 



This example first opens a file myfi 1 e.dat for input and output. It writes integers to 
the file, uses rewi nd to reposition the file pointer to the beginning of the file, and then 
reads the data back in. 

#include <stdio.h> 


FILE *stream; 

int datal,data2,data3,data4; 

int main(void) 

{ 

datal = 1; 
data2 = -37; 

/* Place data in the file */ 

stream = fopenCmyfile.dat", "w+"); 
fprintf(stream, "%d %d\n", datal, data2); 

/* Now read the data file */ 

rewind(stream); 

fscanf(stream, "%d", &data3); 

fscanf(stream, "%d", &data4); 

printf("The values read back in are: %d and %d\n", data3, data4); 
return 0; 

/**************************************************************************** 
The output should be: 

The values read back in are: 1 and -37 

****************************************************************************/ 

} 



“fgetpos — Get File Position” on page 228 
“fseek — Reposition File Position” on page 273 
“fsetpos — Set File Position” on page 275 
“ftel 1 — Get Current Position” on page 283 
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• “1 seek — Move File Pointer” on page 393 

• “_tel 1 — Get Pointer Position” on page 655 

• “<stdio.h>” on page 815 
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rmdir — Remove Directory 

Format linclude <direct.h> 

int rmdir(char *pathname ); 

Description Language Level: XPG4, Extension 

rmdi r deletes the directory specified by pathname. The directory must be empty, and 
it must not be the current working directory or the root directory. 

Note: In earlier releases of C Set ++, rmdi r began with an underscore (_rmdi r). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _rmdi r to rmdi r for you. 

Return Value rmdi r returns the value 0 if the directory is successfully deleted. A return value of 
-1 indicates an error, and errno is set to one of the following values: 

Value Meaning 

EACCESS One of the following has occurred: 

• The given path name is not a directory. 

• The directory is not empty. 

• The directory is read only. 

• The directory is the current working directory or root directory 
being used by a process. 

ENOENT The path name was not found. 

This example deletes two directories: one in the root directory, and the other in the 
current working directory. 

#inc1ude <stdio.h> 

#inc1ude <direct.h> 

#inc1ude <string.h> 

int main(void) 

{ 

char *dirl,*dir2; 

/* Create the directory "aleng" in the root directory of the C: drive. */ 
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dirl = "c:\\aleng"; 
if (0 == (mkdir(dirl))) 

printf("%s directory was created.\n", dirl); 
else 

printf("%s directory was not created.\n", dirl); 

/* Create the subdirectory "simon" in the current directory. */ 

dir2 = "simon"; 

if (0 == (mkdir(dir2))) 

printf("%s directory was created.\n", dir2); 
else 

printf("%s directory was not created.\n", dir2); 

/* Remove the directory "aleng" from the root directory of the C: drive. */ 

printf("Removing directory 'aleng' from the root directory.\n"); 
if (rmdir(dirl)) 
perror(NULL); 
else 

printf("%s directory was removed.\n", dirl); 

/* Remove the subdirectory "simon" from the current directory. */ 

printf("Removing subdirectory 'simon' from the current directory.\n"); 
if (rmdir(dir2)) 
perror(NULL); 
else 

printf("%s directory was removed.\n", dir2); 
return 0; 

/•k-k-k-k-k-k'k-k-kle-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-kle 

The output should be: 

c:\aleng directory was created, 
simon directory was created. 

Removing directory 'aleng' from the root directory. 
c:\aleng directory was removed. 

Removing subdirectory 'simon' from the current directory, 
simon directory was removed. 

****************************************************************************/ 



“chdi r — Change Current Working Directory” on page 87 
“_getdcwd — Get Full Path Name of Current Directory” on page 302 
“_getcwd — Get Path Name of Current Directory” on page 300 
“mkdi r — Create New Directory” on page 436 
“<direct.h>” on page 803 


500 VisualAge C++ C Library Reference 




rmem init 


_rmem_init 

Format 

Description 


Return Value 



- Initialize Memory Functions for Subsystem DLL 

int _rmem_init(void); 

/* no header file - defined in runtime startup code */ 

Language Level: Extension 

_rmem_i n i t initializes the memory functions for subsystem DLLs. Although 
subsystems do not require a runtime environment (and therefore do not call 
_CRT_i ni t), they do require the library memory functions. For DLLs that do use a 
runtime environment, the memory functions are initialized with the environment by 
_CRT_i nit. 

By default, all DLLs call the VisualAge C++ _DLL_Ini tTerm function, which in turn 
calls _rmem_i ni t for you. However, if you are writing your own subsystem 
_DLL_Ini tTerm function (for example, to perform actions other than memory 
initialization and termination), you must call _rmem_init from your version of 
_DLL_Ini tTerm before you can call any other library functions. 

If your DLL contains C++ code, you must also call _ ctordtorlnit after _rmem_init 

to ensure that static constructors and destructors are initialized properly. 

_ctordtorlnit is defined in the runtime startup code as: 

void _ctordtorlnit(void); 

If the memory functions were successfully initialized, _rmem_init returns 0. A 
return code of -1 indicates an error. If an error occurs, an error message is written to 
file handle 2, which is the usual destination of stderr. 

This example shows the _DLL_Ini tTerm function from the VisualAge C++ sample 
program for building subsystem DLLs, which calls _rmem_init to initialize the 
memory functions. 
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#pragma strings( readonly ) 

/•k-k-k‘k-k-k-k-k-ki<-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k-k-k-k‘k-k-k-k-k-ki(-k-k‘k-k-k‘k-k-k‘k-kick-k-k‘k-k-k‘k-k-k^ 


/* */ 

/* _DLL_InitTerm - Initialization/Termination function for the DLL that is */ 

/* invoked by the loader. When the /Ge- compile option is */ 

/* used the linker is told that this is the function to */ 

/* execute when the DLL is first loaded and last freed for */ 

/* each process. */ 

/* */ 

/* DLLREGISTER - Called by _DLL_InitTerm for each process that loads the */ 
/* DLL. */ 

/* */ 

/* DLLDEREGISTER- Called by _DLL_InitTerm for each process that frees the */ 

/* DLL. */ 

/* */ 


/******************************************************************************/ 


#define INCL_D0S 
#define INCL_D0SERR0RS 
#define INCL_NOPMAPI 
#include <os2.h> 

#include <stdio.h> 

unsigned long _System _DLL_InitTerm( unsigned long hModule, unsigned long ul FI ag ); 

static unsigned long DLLREGISTER( void ); 
static unsigned long DLLDEREGISTER( void ); 

#define SHARED_SEMAPHORE_NAME "\\SEM32\\SAMPLE05\\DLL.LCK" 

/* The following data will be per-process data. It will not be shared among */ 


/* different processes. */ 

static HMTX hmtxSharedSem; /* Shared semaphore */ 

static ULONG ulProcessTotal; /* Total of increments for a process */ 

static PID pidProcess; /* Process identifier */ 

/* This is the global data segment that is shared by every process. */ 

#pragma data_seg( GLOBAL_SEG ) 

static ULONG ulProcessCount; /* total number of processes */ 
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/* _DLL_InitTerm() - called by the loader for DLL initialization/termination */ 
/* This function must return a non-zero value if successful and a zero value */ 
/* i f unsuccessful. */ 

unsigned long _DLL_InitTerm( unsigned long hModule, unsigned long ulFIag ) 

{ 

APIRET rc; 


/* If ulFIag is zero then initialization is required: */ 
/* If the shared memory pointer is NULL then the DLL is being loaded */ 
/* for the first time so acquire the named shared storage for the */ 
/* process control structures. A linked list of process control */ 
/* structures will be maintained. Each time a new process loads this */ 
/* DLL, a new process control structure is created and it is inserted */ 
/* at the end of the list by calling DLLREGISTER. */ 
/* */ 
/* If ulFIag is 1 then termination is required: */ 
/* Call DLLDEREGISTER which will remove the process control structure */ 
/* and free the shared memory block from its virtual address space. */ 


switch( ulFIag ) 

{ 

case 0: 

if ( !ulProcessCount ) 

{ 

_rmem_init(); 

/* Create the shared mutex semaphore. */ 

if ( ( rc = DosCreateMutexSem( SHARED_SEMAPHORE_NAME, 

&hmtxSharedSem, 

0, 

FALSE ) ) != N0_ERR0R ) 

{ 

printf( "DosCreateMutexSem rc = %lu\n", rc ); 
return 0; 

} 

} 

/* Register the current process. */ 

if ( DLLREGISTER( ) ) 
return 0; 
break; 

case 1: 

/* De-register the current process. */ 

if ( DLLDEREGISTER( ) ) 
return 0; 

_rmem_term(); 
break; 
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default: 
return 0; 

} 


/* Indicate success. Non-zero means success!!! */ 

return 1; 

} 


/* DLLREGISTER - Registers the current process so that it can use this */ 

/* subsystem. Called by _DLL_InitTerm when the DLL is first */ 

/* loaded for the current process. */ 

static unsigned long DLLREGISTER( void ) 

{ 

APIRET rc; 

PTIB ptib; 

PPIB ppib; 

/* Get the address of the process and thread information blocks. */ 

if ( ( rc = DosGetlnfoBlocks( &ptib, &ppib ) ) != N0_ERR0R ) 

{ 

printf( "DosGetlnfoBlocks rc = %lu\n", rc ); 
return rc; 

} 

/* Open the shared mutex semaphore for this process. */ 

if ( ( rc = DosOpenMutexSem( SHARED_SEMAPHORE_NAME, 

&hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosOpenMutexSem rc = %lu\n", rc ); 
return rc; 

} 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %lu\n", rc ); 

DosCloseMutexSem( hmtxSharedSem ); 
return rc; 

} 

/* Increment the count of processes registered. */ 

++ulProcessCount; 
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/* Initialize the per-process data. */ 

ulProcessTotal = 0; 
pidProcess = ppib->pib_ulpid; 

/* Tell the user that the current process has been registered. */ 

printf( "\nProcess %lu has been registered.\n\n", pidProcess ); 

/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 

return 0; 

} 

/* DLLDEREGISTER - Deregisters the current process from this subsystem. */ 

/* Called by _DLL_InitTerm when the DLL is freed for the */ 

/* last time by the current process. */ 

static unsigned long DLLDEREGISTER( void ) 

{ 

APIRET rc; 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %1u\n", rc ); 
return rc; 

} 

/* Decrement the count of processes registered. */ 

--ulProcessCount; 

/* Tell the user that the current process has been deregistered. */ 

printf( "\nProcess %lu has been deregistered.\n\n", pidProcess ); 

/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 
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/* Close the shared mutex semaphore for this process. */ 

if ( ( rc = DosCloseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosCloseMutexSem rc = %lu\n", rc ); 
return rc; 

} 


return 0; 

} 



Building Subsystem DLLs in the Programming Guide 
“_CRT_i nit — Initialize DLL Runtime Environment” on page 118 
“_CRT_term — Terminate DLL Runtime Environment” on page 122 
“_DLL_Ini tTerm — Initialize and Terminate DLL Environment” on page 170 
“_rmem_term — Terminate Memory Functions for Subsystem DLL” on page 507 
“_tmem_init — Initialize Memory Functions for Subsystem DLL” on page 669 
“_tmem_term — Terminate Memory Functions for Subsystem DLL” on page 670 
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_rmem_term 

Format 

Description 


Return Value 



- Terminate Memory Functions for Subsystem DLL 

int _rmem_term(void); 

/* no header file - defined in runtime startup code */ 

Language Level: Extension 

_rmem_term terminates the memory functions for subsystem DLLs. It is only needed 
for DLLs where the runtime library is statically linked. 

By default, all DLLs call the VisualAge C++ _DLL_Ini tTerm function, which in turn 
calls _rmem_term for you. However, if you are writing your own _DLL_Ini tTerm 
function (for example, to perform actions other than memory initialization and 
termination), and your DLL statically links to the C runtime libraries, you need to call 
_rmem_term from your subsystem _DLL_Ini tTerm function. (For DLLs with a 
runtime environment, this termination is done by _CRT_term.) 

If your DLL contains C++ code, you must also call _ ctordtorTerm before you call 

_rmem_term to ensure that static constructors and destructors are terminated correctly. 
_ctordtorTerm is defined in the runtime startup code as: 

void _ctordtorTerm(void); 

Once you have called _rmem_term, you cannot call any other library functions. 

If your DLL is dynamically linked, you cannot call library functions in the 
termination section of your _DLL_Ini tTerm function. If your termination routine 
requires calling library functions, you must register the termination routine with 
DosExitList. Note that all DosExitList routines are called before DLL termination 
routines. 

_rmem_term returns 0 if the memory functions were successfully terminated. A 
return value of -1 indicates an error. 

This example shows the _DLL_Ini tTerm function from the VisualAge C++ sample 
program for building subsystem DLLs, which calls _rmem_term to terminate the 
library memory functions. 
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#pragma strings( readonly ) 


/* */ 

/* _DLL_InitTerm - Initialization/Termination function for the DLL that is */ 

/* invoked by the loader. When the /Ge- compile option is */ 

/* used the linker is told that this is the function to */ 

/* execute when the DLL is first loaded and last freed for */ 

/* each process. */ 

/* */ 

/* DLLREGISTER - Called by _DLL_InitTerm for each process that loads the */ 
/* DLL. */ 

/* */ 

/* DLLDEREGISTER- Called by _DLL_InitTerm for each process that frees the */ 

/* DLL. */ 

/* */ 


/******************************************************************************/ 


#define INCL_D0S 
#define INCLJMSERRORS 
#define INCLJIOPMAPI 
#include <os2.h> 

#include <stdio.h> 

unsigned long _System _DLL_InitTerm( unsigned long hModule, unsigned long ul FI ag ); 

static unsigned long DLLREGISTER( void ); 
static unsigned long DLLDEREGISTER( void ); 

#define SHARED_SEMAPHORE_NAME "\\SEM32\\SAMPLE05\\DLL.LCK" 

/* The following data will be per-process data. It will not be shared among */ 


/* different processes. */ 

static HMTX hmtxSharedSem; /* Shared semaphore */ 

static ULONG ulProcessTotal; /* Total of increments for a process */ 

static PID pidProcess; /* Process identifier */ 

/* This is the global data segment that is shared by every process. */ 

#pragma data_seg( GLOBAL_SEG ) 

static ULONG ulProcessCount; /* total number of processes */ 
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/* _DLL_InitTerm() - called by the loader for DLL initialization/termination */ 
/* This function must return a non-zero value if successful and a zero value */ 
/* i f unsuccessful. */ 

unsigned long _DLL_InitTerm( unsigned long hModule, unsigned long ulFIag ) 

{ 

APIRET rc; 


/* If ulFIag is zero then initialization is required: */ 
/* If the shared memory pointer is NULL then the DLL is being loaded */ 
/* for the first time so acquire the named shared storage for the */ 
/* process control structures. A linked list of process control */ 
/* structures will be maintained. Each time a new process loads this */ 
/* DLL, a new process control structure is created and it is inserted */ 
/* at the end of the list by calling DLLREGISTER. */ 
/* */ 
/* If ulFIag is 1 then termination is required: */ 
/* Call DLLDEREGISTER which will remove the process control structure */ 
/* and free the shared memory block from its virtual address space. */ 


switch( ulFIag ) 

{ 

case 0: 

if ( !ulProcessCount ) 

{ 

_rmem_init(); 

/* Create the shared mutex semaphore. */ 

if ( ( rc = DosCreateMutexSem( SHARED_SEMAPHORE_NAME, 

&hmtxSharedSem, 

0, 

FALSE ) ) != N0_ERR0R ) 

{ 

printf( "DosCreateMutexSem rc = %lu\n", rc ); 
return 0; 

} 

} 

/* Register the current process. */ 

if ( DLLREGISTER( ) ) 
return 0; 
break; 

case 1: 

/* De-register the current process. */ 

if ( DLLDEREGISTER( ) ) 
return 0; 

_rmem_term(); 
break; 
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default: 
return 0; 

} 


/* Indicate success. Non-zero means success!!! */ 

return 1; 

} 


/* DLLREGISTER - Registers the current process so that it can use this */ 

/* subsystem. Called by _DLL_InitTerm when the DLL is first */ 

/* loaded for the current process. */ 

static unsigned long DLLREGISTER( void ) 

{ 

APIRET rc; 

PTIB ptib; 

PPIB ppib; 

/* Get the address of the process and thread information blocks. */ 

if ( ( rc = DosGetlnfoBlocks( &ptib, &ppib ) ) != N0_ERR0R ) 

{ 

printf( "DosGetlnfoBlocks rc = %lu\n", rc ); 
return rc; 

} 

/* Open the shared mutex semaphore for this process. */ 

if ( ( rc = DosOpenMutexSem( SHARED_SEMAPHORE_NAME, 

&hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosOpenMutexSem rc = %lu\n", rc ); 
return rc; 

} 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %lu\n", rc ); 

DosCloseMutexSem( hmtxSharedSem ); 
return rc; 

} 

/* Increment the count of processes registered. */ 

++ulProcessCount; 
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/* Initialize the per-process data. */ 

ulProcessTotal = 0; 
pidProcess = ppib->pib_ulpid; 

/* Tell the user that the current process has been registered. */ 

printf( "\nProcess %lu has been registered.\n\n", pidProcess ); 

/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 

return 0; 

} 

/* DLLDEREGISTER - Deregisters the current process from this subsystem. */ 

/* Called by _DLL_InitTerm when the DLL is freed for the */ 

/* last time by the current process. */ 

static unsigned long DLLDEREGISTER( void ) 

{ 

APIRET rc; 

/* Acquire the shared mutex semaphore. */ 

if ( ( rc = DosRequestMutexSem( hmtxSharedSem, 

SEM_INDEFINITE_WAIT ) ) != N0_ERR0R ) 

{ 

printf( "DosRequestMutexSem rc = %1u\n", rc ); 
return rc; 

} 

/* Decrement the count of processes registered. */ 

--ulProcessCount; 

/* Tell the user that the current process has been deregistered. */ 

printf( "\nProcess %lu has been deregistered.\n\n", pidProcess ); 

/* Release the shared mutex semaphore. */ 

if ( ( rc = DosReleaseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosReleaseMutexSem rc = %lu\n", rc ); 
return rc; 

} 
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/* Close the shared mutex semaphore for this process. */ 

if ( ( rc = DosCloseMutexSem( hmtxSharedSem ) ) != N0_ERR0R ) 

{ 

printf( "DosCloseMutexSem rc = %lu\n", rc ); 
return rc; 

} 


return 0; 

} 



Building Subsystem DLLs in the Programming Guide 
“_CRT_i nit — Initialize DLL Runtime Environment” on page 118 
“_CRT_term — Terminate DLL Runtime Environment” on page 122 
“_DLL_Ini tTerm — Initialize and Terminate DLL Environment” on page 170 
“_rmem_init — Initialize Memory Functions for Subsystem DLL” on page 501 
“_tmem_init — Initialize Memory Functions for Subsystem DLL” on page 669 
“_tmem_term — Terminate Memory Functions for Subsystem DLL” on page 670 
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rmtmp — Remove Temporary Files 

Format linclude <stdio.h> 

int _rmtmp(void); 

Description Language Level: Extension 

_rmtmp closes and deletes all temporary files in all directories that are held open by 
the calling process. 

Return Value _rmtmp returns the number of temporary files deleted. 

This example uses _rmtmp to remove a number of temporary files. 

#inc1ude <stdio.h> 

int main(void) 

{ 

int num; 

FILE *stream; 

if (NULL == (stream = tmpfile())) 

printf("Could not open new temporary fi1e\n"); 
el se { 

num = _rmtmp(); 

printf("Number of temporary files removed = %d\n", num); 

} 

return 0; 

/**************************************************************************** 

The output should be: 

Number of temporary files removed = 1 

****************************************************************************/ 

i 

• “_f 1 ushal 1 — Write Buffers to Files” on page 240 

• “remove — Delete File” on page 495 

• “tmpfile — Create Temporary File” on page 671 

• “tmpnam — Produce Temporary File Name” on page 672 

• “uni ink — Delete File” on page 729 

• “<stdio.h>” on page 815 
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_rotl - rotr — Rotate Bits of Unsigned Integer 

Format linclude <stdlib.h> /* also in <builtin.h> */ 

unsigned int _rotl(unsigned int value, int shift); 
unsigned int _rotr(unsigned int value, int shift); 

Description Language Level: Extension 

These functions take a 4-byte integer value and rotate it by shift bits. _rotl 
rotates to the left, and _rotr to the right. 

Note: Both jrotl and _rotr are built-in functions, which means they are 

implemented as inline instructions and have no backing code in the library. 
For this reason: 

• You cannot take the address of these functions. 

• You cannot parenthesize a call to either function. (Parentheses specify a 
call to the backing code for the function in the runtime library.) 

Portability Consideration: Because the size of an int is only 2 bytes in 16-bit 
compilers, if you are migrating 16-bit programs, some parts of your programs may 
have to be rewritten if they use this function. 

Return Value Both functions return the rotated value. There is no error return. 

This example uses _rotr and _rotl with different shift values to rotate the integer 
value 0x01234567: 

linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

unsigned int val = 0X01234567; 

printf("The value of 0x%8.81x rotated 4 bits to the left is 0x%8.81x\n", val, 

_rotl(val, 4)); 

printf("The value of 0x%8.81x rotated 16 bits to the right is 0x%8.81x\n", 
val, _rotr(val, 16)); 
return 0; 

/**************************************************************************** 

The output should be: 

The value of 0x01234567 rotated 4 bits to the left is 0x12345670 
The value of 0x01234567 rotated 16 bits to the right is 0x45670123 
****************************************************************************/ 

} 

“_crotl - _crotr — Rotate Bits of Character Value” on page 117 
“_1 rotl - _1 rotr — Rotate Bits of Unsigned Long Value” on page 392 
“_srotl - _srotr — Rotate Bits of Unsigned Short Value” on page 558 
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“swab — Swap Adjacent Bytes” on page 634 
“<builtin.h>” on page 801 
“<stdlib.h>” on page 816 
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rpmatch — Test for Yes/No Response Match 

Format linclude <stdlib.h> 

int rpmatch(const char *response); 

Description Language Level: POSIX, Extension 

rpmatch tests whether the string pointed to by response matches either the 
affirmative or the negative response set by LC_MESSAGES category in the current 
locale. 


Return Value rpmatch returns: 

1 If the response string matches the affirmative expression. 

0 If the response string matches the negative expression. 

-1 If the response string does not match either the affirmative or the negative 

expression. 



This example asks for a reply, and checks the response. 

#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *response; 
char buffer[lO0]; 
int rc; 


printf("Enter reply:\n"); 

response = fgets(buffer, 100, stdin); 

rc = rpmatch(response); 

if (rc > 0) 

printf("Response was affirmative\n"); 
else if (rc == 0) 

printf("Response was negative\n"); 
el se 

printf("Response was neither negative or affirmative\n"); 
return 0; 


/**************************************************************************** 
Assuming you enter : No 

The output should be : 

Response was negative 

****************************************************************************/ 

} 



“setlocale — Set Locale” on page 530 
“<stdlib.h>” on page 816 
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scanf — Read Data 

Format linclude <stdio.h> 

int scanf(const char *format-string , argument-list); 

Description Language Level: ANSI, ANSI 93, SAA, POSIX, XPG4, Extension 

scanf reads data from the standard input stream stdin into the locations given by each 
entry in argument-1 ist. Each argument must be a pointer to a variable with a type 
that corresponds to a type specifier in format-string. The format-string controls 
the interpretation of the input fields. 

The format-string can contain one or more of the following: 

• White-space characters, as specified by isspace (such as blanks and new-line 
characters). A white-space character causes scanf to read, but not to store, all 
consecutive white-space characters in the input up to the next character that is not 
white space. One white-space character in format-string matches any 
combination of white-space characters in the input. 

• Characters that are not white space, except for the percent sign character (%). A 
non-white-space character causes scanf to read, but not to store, a matching 
non-white-space character. If the next character in stdin does not match, scanf 
ends. 

• Format specifications, introduced by the percent sign (%). A format specification 
causes scanf to read and convert characters in the input into values of a specified 
type. The value is assigned to an argument in the argument list. 

scanf reads format-string from left to right. Characters outside of format 
specifications are expected to match the sequence of characters in stdin; the matched 
characters in stdin are scanned but not stored. If a character in stdin conflicts with 
format-string, scanf ends. The conflicting character is left in stdin as if it had not 
been read. 

When the first format specification is found, the value of the first input field is 
converted according to the format specification and stored in the location specified by 
the first entry in argument-list. The second format specification converts the 
second input field and stores it in the second entry in argument-list, and so on 
through the end of format-string. 

An input field is defined as all characters up to the first white-space character (space, 
tab, or new line), up to the first character that cannot be converted according to the 
format specification, or until the field width is reached, whichever comes first. If 
there are too many arguments for the format specifications, the extra arguments are 
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ignored. The results are undefined if there are not enough arguments for the format 
specifications. 


A format specification has the following form: 



L*J Ljvidtb—1 

-h- 

-1- 



Each field of the format specification is a single character or a number signifying a 
particular' format option. The type character, which appears after the last optional 
format field, determines whether the input field is interpreted as a character, a string, 
or a number. The simplest format specification contains only the percent sign and a 
type character (for example, %s). 

Each field of the format specification is discussed in detail below. If a percent sign 
(%) is followed by a character that has no meaning as a format control character, that 
character and following characters up to the next percent sign are treated as an 
ordinary sequence of characters; that is, a sequence of characters that must match the 
input. For example, to specify a percent-sign character, use %%. 

An asterisk (*) following the percent sign suppresses assignment of the next input 
field, which is interpreted as a field of the specified type. The field is scanned but 
not stored. 

The width is a positive decimal integer controlling the maximum number of 
characters to be read from stdin. No more than width characters are converted and 
stored at the corresponding argument. Fewer than width characters are read if a 
white-space character (space, tab, or new line), or a character that cannot be 
converted according to the given format occurs before width is reached. 

The optional prefix 1 shows that you use the 1 ong version of the following type , 
while the prefix h indicates that the short version is to be used. The corresponding 
argument should point to a long or double object (for the 1 character), a long 
double object (for the L character), or a short object (with the h character). The 1 
and h modifiers can be used with the d, i, o, x, and u type characters. The 1 
modifier can also be used with the e, f, and g type characters. The L modifier can 
be used with the e, f and g type characters. The 1 and h modifiers are ignored if 
specified for any other type. Note that the 1 modifier is also used with the c and s 
characters to indicate a multibyte character or string. 
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The type characters and their meanings are in the following table: 


Character 

Type of Input Expected 

Type of Argument 

d 

Decimal integer 

Pointer to i nt 

0 

Octal integer 

Pointer to unsigned int 

x, X 

Hexadecimal integer 

Pointer to unsigned int 

i 

Decimal, hexadecimal, or octal 
integer 

Pointer to i nt 

u 

Unsigned decimal integer 

Pointer to unsigned int 

e, f, g 

E, G 

Floating-point value consisting of an 
optional sign (+ or -); a series of 
one or more decimal digits possibly 
containing a decimal point; and an 
optional exponent (e or E) followed 
by a possibly signed integer value. 

Pointer to f ' 1 oat 

c 

Character; white-space characters 
that are ordinarily skipped are read 
when c is specified 

Pointer to char large enough for input 
field 

1c 

Multibyte characters. The multibyte 
characters are converted to wide 
characters as if by a call to 
mbrtowc. The field width specifies 
the number of wide characters 
matched; if no width is specified, 
one character is matched. 

Pointer to wchar_t large enough for 
input field 

s 

String 

Pointer to character array large 
enough for input field plus a 
terminating null character (\0), which 
is automatically appended 

Is 

Multibyte string. None of the 
characters can be single-byte 
white-space characters (as specified 
by the isspace function). Each 
muitibyte character in the sequence 
is converted to a wide character as 
if by a call to mbrtowc. 

Pointer to wchar_t array large enough 
for the input field and the terminating 
null wide character (L\0), which is 
added automatically. 

n 

No input read from stream or 
buffer 

Pointer to i nt, into which is stored 
the number of characters successfully 
read from the stream or buffer up to 
that point in the call to scanf 

p 

Pointer to void converted to series 

Pointer to voi d 


of characters 


Chapter 3. Library Functions 519 




scanf 


Return Value 



To read strings not delimited by space characters, substitute a set of characters in 
brackets ([ ]) for the s (string) type character. The corresponding input field is read 
up to the first character that does not appear in the bracketed character set. If the 
first character in the set is a caret ( /v ), the effect is reversed: the input field is read up 
to the first character that does appear in the rest of the character set. 

To store a string without storing an ending null character (\0), use the specification 
%oc, where a is a decimal integer. In this instance, the c type character means that 
the argument is a pointer to a character array. The next a characters are read from 
the input stream into the specified location, and no null character is added. 

The input for a %x format specifier is interpreted as a hexadecimal number. 

scanf scans each input field character by character. It might stop reading a particular 
input field either before it reaches a space character, when the specified width is 
reached, or when the next character cannot be converted as specified. When a 
conflict occurs between the specification and the input character, the next input field 
begins at the first unread character. The conflicting character, if there was one, is 
considered unread and is the first character of the next input field or the first 
character in subsequent read operations on stdin. 

scanf returns the number of fields that were successfully converted and assigned. 

The return value does not include fields that were read but not assigned. 

The return value is EOF for an attempt to read at end-of-file if no conversion was 
performed. A return value of 0 means that no fields were assigned. 

This example scans various types of data. 

#include <stdio.h> 

int main(void) 

{ 

i nt i; 
float fp; 
char c,s[81]; 

printf("Enter an integer, a real number, a character and a string : \n"); 
if (scanf("%d %f %c %s", &i, &fp, &c, s) != 4) 
printf("Not all of the fields were assigned\n"); 
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el se { 

printf("integer = %d\n", i); 
printf("real number = %f\n", fp); 
printf("character = %c\n", c); 
printf("string = %s\n", s); 

} 

return 0; 

/**************************************************************************** 
The output should be similar to: 

Enter an integer, a real number, a character and a string : 

12 2.5 a yes 
integer = 12 
real number = 2.500000 
character = a 
string = yes 

****************************************************************************/ 

} 


This example converts a hexadecimal integer to a decimal integer. The while loop 
ends if the input value is not a hexadecimal integer. 

#include <stdio.h> 

int main(void) 

{ 

int number; 

printf("Enter a hexadecimal number or anything else to quit:\n"); 
while (scanf("%x", &number)) { 

printf("Hexadecimal Number = %x\n", number); 
printf("Decimal Number = %d\n", number); 

1 

return 0; 

/**************************************************************************** 

The output should be similar to: 

Enter a hexadecimal number or anything else to quit: 

0x231 

Hexadecimal Number = 231 
Decimal Number = 561 
0xf5e 

Hexadecimal Number = f5e 
Decimal Number = 3934 
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0x1 

Hexadecimal Number = 1 
Decimal Number = 1 

q 

} 



“_cscanf — Read Data from Keyboard” on page 127 
“fscanf — Read Formatted Data” on page 271 
“printf — Print Formatted Characters” on page 461 
“sscanf — Read Data” on page 559 
“<stdio.h>” on page 815 
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_searchenv 

Format 

Description 


Return Value 



- Search for File 

linclude <stdlib.h> 

void _searchenv(char *name, char *env_var, char *path ); 

Language Level: Extension 

_searchenv searches for the target file in the specified domain. The env_var 
variable can be any environment variable that specifies a list of directory paths, such 
as PATH, LIB, INCLUDE, or other user-defined variables. Most often, it is PATH, 
causing a search for name in all directories specified in the PATH variable. 

The routine first searches for the file in the current working directory. If it does not 
find the file, it next looks through the directories specified by the environment 
variable. 

If the target file is found in one of the directories, the fully-qualified file name is 
copied into the buffer that path points to. You must ensure sufficient space for the 
constructed file name. If the target file is not found, path contains an empty 
null-terminated string. 


There is no return value. 

This example searches for the files searchen.c and cmd.exe. 

#include <stdio.h> 

#include <std1ib.h> 

int main(void) 

{ 

char path_buffer[_MAX_PATH]; 

_searchenvCcmd.exe", "PATH", path_buffer); 
printf("path: %s\n", path_buffer); 

_searchenv("_searche.c", "DPATH", path_buffer); 
printf("path: %s\n", path_buffer); 
return 0; 

/**************************************************************************** 
The output should be similar to: 

path: C:\0S2\cmd.exe 
path: C:\src\_searche.c 

****************************************************************************/ 


• “getenv — Search for Environment Variables” on page 305 

• “putenv — Modify Environment Variables” on page 471 

• “<stdlib.h>” on page 816 


Chapter 3. Library Functions 523 



setbuf 


setbuf — Control Buffering 

Format linclude <stdio.h> 

void setbuf(FILE *stream, char *buffer); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

setbuf controls buffering for the specified stream. The stream pointer must refer to 
an open file before any I/O or repositioning has been done. 

If the buffer argument is NULL, the stream is unbuffered. If not, the buffer must 
point to a character array of length BUFSIZ, which is the buffer size defined in the 
<stdio.h> include file. The system uses the buffer, which you specify, for 
input/output buffering instead of the default system-allocated buffer for the given 
stream. 


setvbuf is more flexible than setbuf. 

Note: Under VisualAge C++, streams are fully buffered by default, with the 
exceptions of stderr, which is line-buffered, and memory files, which are unbuffered. 


Return Value There is no return value. 



This example opens the file setbuf.dat for writing. It then calls setbuf to establish a 
buffer of length BUFSIZ. When string is written to the stream, the buffer buf is used 
and contains the string before it is flushed to the file. 


#include <stdio.h> 


#define FILENAME "setbuf.dat" 

int main(void) 

{ 

char buf[BUFSIZ]; 

char string[] = "hello world"; 

FILE *stream; 

memset(buf, '\0', BUFSIZ); /* initialize buf to null characters */ 

stream = fopen(FILENAME, "wb"); 

setbuf(stream, buf); /* set up buffer */ 

fwrite(string, sizeof(string), 1, stream); 


524 VisualAge C++ C Library Reference 



setbuf 


printf("%s\n", buf); /* string is found in buf now */ 

fclose(stream); /* buffer is flushed out to output stream */ 

return 0; 

/**************************************************************************** 

The output file should contain: 

hello world 

The output should be: 

hello world 

****************************************************************************/ 


• “fcl ose — Close Stream” on page 212 

• “ffl ush — Write Buffer to File” on page 224 

• “_f 1 ushal 1 — Write Buffers to Files” on page 240 

• “fopen — Open Files” on page 243 

• “setvbuf — Control Buffering” on page 538 

• “<stdio.h>” on page 815 
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_set_crt_msg_handle — Change Runtime Message Output Destination 

Format linclude <stdio.h> 

int _set_crt_msg_handle(int fh); 

Description Language Level: Extension 

_set_crt_msg_handl e changes the file handle to which runtime messages are sent, 
which is usually file handle 2, to fh. Runtime messages include exception handling 
messages and output from debug memory management routines. 

Use _set_crt_msg_handl e to trap runtime message output in applications where 
handle 2 is not defined, such as Presentation Manager applications. 

The file handle fh must be a writable file or pipe handle. Set fh only for the current 
library environment. 

Return Value _set_crt_msg_handl e returns the handle to be used for runtime message output. If 
an handle that is not valid is passed as an argument, it is ignored and no change takes 
place. 

This example causes an exception by dereferencing a null pointer and uses 
_set_crt_msg_handl e to send the exception messages to the file _scmhdl .out. 

linclude <sys\stat.h> 
linclude <io.h> 
linclude <fcntl.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

int fh; 
char *p = NULL; 

if (-1 == (fh = open("_scmhdl.out", 0_CREAT|0_TRUNC|0_RDWR, 

SIREAD|S_IWRITE))) { 

perror("Unable to open the file _scmhdl.out."); 
exit(EXIT_FAILURE); 

} 
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/* change file handle where messages are sent */ 
if (fh != _set_crt_msg_handle(fh)) { 

perror("Could not change massage output handle."); 
exit(EXIT_FAILURE); 

} 

*p = 'x'; /* cause an exception, output should be in _scmhdl.out */ 

if (-1 == close(fh)) { 

perror("Unable to close _scmhdl.out."); 
exit(EXIT_FAILURE); 

} 

return 0; 

/**************************************************************************** 
Running this program would cause an exception to occur, 
the file _scmhdl.out should contain the exception messages similar to : 

Exception = C0000005 occurred at EIP = 10068. 
****************************************************************************/ 


“open — Open File” on page 447 
“fi 1 eno — Determine File Handle” on page 238 
“_Sopen — Open Shared File” on page 545 
“<stdio.h>” on page 815 
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setjmp — Preserve Environment 

Format linclude <setjmp.h> 

int setjmp(jmp_buf env); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

setjmp saves a stack environment that can subsequently be restored by longjmp. 
setjmp and longjmp provide a way to perform a nonlocal goto. They are often used 
in signal handlers. 

A call to setjmp causes it to save the current stack environment in env. A subsequent 
call to longjmp restores the saved environment and returns control to a point 
corresponding to the setjmp call. The values of all variables (except register 
variables) accessible to the function receiving control contain the values they had 
when longjmp was called. The values of variables that are allocated to registers by 
the compiler are unpredictable. Because any auto variable could be allocated to a 
register in optimized code, you should consider the values of all auto variables to be 
unpredictable after a longjmp call. 

C++ Considerations: When you call setjmp in a C++ program, ensure that that part 
of the program does not also create C++ objects that need to be destroyed. 
When you call longjmp, objects existing at the time of the setjmp call will 
still exist, but any destructors called after setjmp are not called. See 
“longjmp — Restore Stack Environment” on page 389 for an example. 

Return Value setjmp returns the value 0 after saving the stack environment. If setjmp returns as a 
result of a longjmp call, it returns the value argument of longjmp, or 1 if the value 
argument of longjmp is 0. There is no error return value. 

This example stores the stack environment at the statement 
if(setjmp(mark) != 0) ... 

When the system first performs the i f statement, it saves the environment in mark 
and sets the condition to FALSE because setjmp returns a 0 when it saves the 
environment. The program prints the message 
setjmp has been called 

The subsequent call to function p tests for a local error condition, which can cause it 
to perform the longjmp function. Then, control returns to the original setjmp function 
using the environment saved in mark. This time, the condition is TRUE because -1 is 
the return value from the longjmp function. The program then performs the 
statements in the block and prints 
longjmp has been called 
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Then the program calls the recover function and exits. 

#include <stdio.h> 

#include <stdlib.h> 
lire!ude <setjmp.h> 

jmp_buf mark; 

void p(void) 

{ 

int error = 0; 

error = 9; 

if (error != 0) 

longjmp(mark, -1); 

} 


void recover(void) 

{ 

} 

int main(void) 

{ 

if (setjmp(mark) != 0) { 

printf("1ongjmp has been called\n"); 
recover(); 
return 0; 

} 

printf("setjmp has been called\n"); 

P()s 

return 0; 

/**************************************************************************** 
The output should be: 

setjmp has been called 
1ongjmp has been called 

****************************************************************************/ 

} 


• “1 ongjmp — Restore Stack Environment” on page 389 

• goto in the Language Reference 

• “<setjmp.h>” on page 813 
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setlocale — Set Locale 

Format linclude <locale.h> 

char *setlocale(int category, const char *locale ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

setlocale sets or queries the specified category of the program's locale. A locale 
is the complete definition of that part of a program that depends on language and 
cultural conventions. 

The default VisualAge C++ locale is the POSIX C locale definition, represented as 
"C" or "POSIX". This locale is standard for all ANSI-conforming and 
POSIX-conforming compilers. You can accept the default, or you can use setlocale 
to set the locale to one of the supplied locales listed in “Introduction to Locale” in the 
Programming Guide. 

Some examples of the supplied locales as you would specify them for setlocale are: 

"En_GB. IBM-850" (English, Great Britain, code page 850) 

"Fr_CA.IBM-863" (French, Canada, code page 863) 

"Ja_JP.IBM-932" (Japanese, Japan, code page 932) 

Notes: 

1. If you are already using the code page for one of these locales, you can specify 
the locale name without the code page. For example, if you are using code page 
850, you can specify "En_GB" for the English Great Britain locale. 

2. In earlier versions of C Set ++, you could also specify locales using the macros 
LC_C, LC_C_GERMANY, LC_C_FRANCE, LC_C_SPAIN, LC_C_ITALY, 
LC_C_JAPAN, LC_C_USA, or LC_C_UK. These macros are provided only for 
compatibility with earlier releases; you can still use these macros, but the locales 
they specify are not POSIX locales. 

The result of setlocale depends on the arguments you specify: 

• To set a category to a specific locale , specify both the category and locale 
names. For example: 

setlocale(LC_CTYPE, "POSIX"); 

sets the LC_CTYPE category according to the "POSIX" locale. The category 
names and their purpose are described in the table below. 


530 


VisualAge C++ C Library Reference 



setlocale 


If you specify a null string ("") for locale, setlocale checks locale-related 
environment variables in the program's environment to find a locale name or 
names to use for category. If category is not LC_ALL, setlocale gets the 
locale name from: 

1. LC_ALL, if it is defined and not null 

2. The environment variable with the same name as category , if it is defined 
and not null 

3. LANG, if it is defined and not null 

4. If none of these variables is defined to a valid locale name, setlocale uses 
the "C" locale. 

For example, if the LC_ALL environment variable is set to "GERM" (Germany 
locale): 

setlocale(LC_TIME, 

sets the LC_TIME category to the "GERM" locale. 

If category is LC_ALL and locale is a null string, setlocale checks the 
environment variables in the same order listed above. However, it checks the 
variable for each category and sets the category to the locale specified, which 
could be different for each category. (By contrast, if you specified LC_ALL and 
a specific locale name, all categories would be set to the same locale that you 
specify.) The string returned lists all the locales for all the categories. 

• To query the locale for a category, specify a null pointer for locale. 

setlocale then returns a string indicating the locale setting for that category, 
without changing it. For example: 

char *s = setlocale(LC_CTYPE, NULL); 

returns the current locale for the LC_CTYPE category. 


You can set the category argument of setlocale to one of these values: 


Table 4 (Page 1 of 3). 

Locale Categories for setlocale 

Category 

Purpose 

LC_ALL 

Specifies all categories associated with the program's locale. 

LC_COLLATE 

Defines the collation sequence, that is, the relative order of collation elements (characters and 
multicharacter collation elements) in the program's locale. The collation sequence definition 
is used by regular expression, pattern matching, and sorting functions. Affects the regular 
expression functions regcomp and regexec; the string functions strcoll, strxfrm, wcscoll, 
and wcsxfrm; and the collating functions col 1 equi v, col 1 order, col 1 range, col 1 tostr, 
i smccol 1 el, maxcol 1 , and strtocol 1 . 


Note: Because both LC_CTYPE and LC_COLLATE modify the same storage area, setting 
LC_CTYPE and LC_COLLATE to different categories causes unpredictable results. 
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Table 4 (Page 2 of 3). 

Locale Categories for setlocale 

Category 

Purpose 

LC_CTYPE 

Defines character classification and case conversion for characters in the program's locale. 
Affects the behavior of character-handling functions defined in the <ctype.h> header file: 
csid, isalnum, isalpha, isblank, iswblank iscntrl, isdigit, isgraph, islower, 
isprint, ispunct. isspace, isupper, iswalnum, iswalpha, iswcntrl, iswctype, 
iswdigit, iswgraph, iswlower, iswprint, iswpunct, iswspace, iswupper, iswxdigit, 
isxdigit, tolower, toupper, towlower, towupper, wcsid, and wctype. 

Affects behavior of the printf and scanf families of functions: fprintf, printf, sprintf, 
swprintf, vfprintf, vprintf, vsprintf, vswprintf; fscanf, scanf, sscanf, and 
swscanf. 

Affects the behavior of wide character input/output functions: fgetwc, fgetws, getwc, 
getwchar, fputwc, fputws, putwc, putwchar, and ungetwc. 

Affects the behavior of multibyte and wide character conversion functions: mblen, mbrlen, 
mbrtowc, mbsrtowcs, mbstowcs, mbtowc, wcrtomb, wcsrtombs, wcstod, wcstol, wcstombs, 
wcstoul, wcswidth, wctomb, and wcwidth. 

Note: Because both LC_CTYPE and LC_COLLATE modify the same storage area, setting 
LC_CTYPE and LC_COLLATE to different categories causes unpredictable results. 

LC_MESSAGES 

Under VisualAge C++, affects the values returned by nl langinfo and also defines 
affirmative and negative response patterns, which affect rpmatch. 

LC_MESSAGES does not affect the messages for the following functions: perror, 
strerror, _strerror, and regerror. 

LC_MONETARY 

Affects monetary information returned by localeconv and strfmon. It defines the rules and 
symbols used to format monetary numeric information in the program's locale. The 
formatting rules and symbols are strings, local econv returns pointers to these strings with 
names found in the <locale.h> header file. 

LC_NUMERIC 

Affects the decimal-point character for the formatted input/output and string conversion 
functions, and the nonmonetary formatting information returned by the local econv function, 
specifically: 

• printf family of functions 

• scanf family of functions 

• strtod 

• atof. 

LC_TIME 

Defines time and date format information in the program's locale, affecting the strftime 
strptime, and wcsftime functions. 

LC_SYNTAX 

Affects the values that can be retrieved by the getsyntx function. It does not affect the 
behavior of functions that are dependent on the encoded values for formatting characters, as 
it may do on other platforms. 
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Table 4 (Page 3 of 3). Locale Categories for setlocale 

Category Purpose 

LC_TOD Affects the behavior of the functions related to time zone and Daylight Savings Time 

information in the program's locale, ctime, local time, mktime, setlocale, and strftime 
call the tzset function to override the LC_TOD category information when TZ is defined and 
valid. 


Return Value setlocale returns a string that specifies the locale for the category. If you 

specified "" for locale , the string names the current locale; otherwise, it indicates 
the new locale that the category was set to. 

If you specified LC_ALL for category, the returned string can be either a single 
locale name or, if the individual categories have different locales, a list of the locale 
names for each category in the following order: 

1. LC_COLLATE 

2. LC_CTYPE 

3. LC_MONETARY 

4. LC_NUMERIC 

5. LC_TIME 

6. LC_TOD 

7. LC_MESSAGES 

8. LC_SYNTAX 


The string can be used on a subsequent call to restore that part of the program's 
locale. Because the returned string can be overwritten by subsequent calls to 
setl ocal e, you should copy the string if you plan to use it later. 


If an error occurs, setlocale returns NULL and does not alter the program's locale. 
Errors can occur if the category or locale is not valid, or if the value of the 
environment variable for a category does not contain a valid locale. 



This example sets the locale of the program to be "fr_fr. i bm-850" and prints the 
string that is associated with the locale. 
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#include <stdio.h> 

#include <locale.h> 

int main(void) 

{ 

char *string; 

if (NULL == (string = setlocale(LC_ALL, "fr_fr.ibm-850"))) 
printf("setlocale failed.\n"); 
el se 

printf("The current locale is set to %s.\n", string); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

The current locale is set to fr_fr.ibm-850. 
****************************************************************************/ 

} 


This example uses setenv to set the value of the environment variable LC_TIME to 
FRAN, calls setlocale to set all categories to default values, then query all 
categories, and uses printf to print results. 

#include <1ocale.h> 
linclude <stdio.h> 

int main(void) 

{ 

char *string; 

_putenv("LC_TIME=FRAN"); 

if (NULL == (string = setlocale(LC_ALL, ""))) 
printf("setlocale failed.\n"); 
else 

printf("The current locale categories are: \"%s\"\n", string); 
return 0; 

/•k-k-k-k-k-kic-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-kick-k-k-k-k-k 

The output should be similar to : 

The current locale categories are: "C,C,C,C,FRAN,C,C,C" 

■k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k1c-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k1<‘k-k-k‘k-k-k‘k-k-k1ck1</ 

} 



“Introduction to Locale” in the Programming Guide 
“getenv — Search for Environment Variables” on page 305 
“localeconv — Retrieve Information from the Environment” on page 381 
“<locale.h>” on page 806 
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_setmode — 

Format 

Description 


Return Value 



Set File Translation Mode 

linclude <fcntl.h> 
linclude <io.h> 

int _setmode(int handle, int mode); 

Language Level: Extension 

_setmode sets the translation mode of the file given by handle to mode. The mode 
must be one of the values in the following table: 

Value Meaning 

0_TEXT Sets the translated text mode. Carriage-return line-feed 

combinations are translated into a single line feed on input. 
Line-feed characters are translated into carriage-return line-feed 
combinations on output. 

0_BINARY Sets the binary (untranslated) mode. The above translations are 
suppressed. 

Use _setmode to change the translation mode of a file handle. The translation mode 
only affects the read and write functions. _setmode does not affect the translation 
mode of streams. 

If a file handle is acquired other than by a call to open, creat, _sopen or fi 1 eno, 
you should call _setmode for that file handle before using it within the read or 
write functions. 

_setmode returns the previous translation mode if successful. A return value of -1 
indicates an error, and errno is set to one of the following values: 

Value Meaning 

EBADF The file handle is not a handle for an open file. 

EINVAL Incorrect mode (neither 0_TEXT nor 0_BINARY) 

This example uses open to create the file setmode.dat and writes to it. The program 
then uses _setmode to change the translation mode of setmode.dat from binary to 
text. 
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#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl.h> 

#include <io.h> 

#include <sys\stat.h> 

#define FILENAME "setmode.dat" 

/* routine to validate return codes */ 

void ckrc(int rc) 

{ 

if (-1 == rc) { 

printf("Unexpected return code - -1\n"); 
remove(FILENAME); 
exit(EXIT_FAILURE); 



int main(void) 

{ 

int h; 

int xfer; 

int mode; 

char rbuf[256]; 

char wbuf[] = "123\n456\n"; 

ckrc(h = open(FILENAME, 0_CREAT|0_RDWR|0_TRUNC|0_TEXT, S_IREAD|S_IWRITE)); 
ckrc(write(h, wbuf, sizeof(wbuf))); /* write the file (text) */ 

ckrc(lseek(h, 0, SEEK_SET)); /* seek back to the start of the file */ 

ckrc(xfer = read(h, rbuf, 5)); /* read the file text */ 

printf("Read in %d characters (4 expected)\n", xfer); 
ckrc(mode = _setmode(h, 0_BINARY)); 
if (0_TEXT == mode) 

printf("Mode changed from binary to text\n"); 
else 

printf("Previous mode was not text (unexpected)\n"); 
ckrc(xfer = read(h, rbuf, 5)); /* read the file (binary) */ 

printf("Read in %d characters (5 expected)\n", xfer); 
ckrc(close(h)); 
remove(FILENAME); 
return 0; 

/****'***********'*'***************'************************'*******'*'*'***'*'*'******* 
The output should be: 

Read in 4 characters (4 expected) 

Mode changed from binary to text 
Read in 5 characters (5 expected) 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kic-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kick-kick-kick-k-k-k-kick-k'k-k-k^ 

} 



“creat — Create New File” on page 115 
“open — Open File” on page 447 
“_sopen — Open Shared File” on page 545 
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• “read — Read Into Buffer” on page 482 

• “wri te — Writes from Buffer to File” on page 799 

• “<fcntl.h>” on page 803 

• “<io.h>” on page 804 

• “<share.h>” on page 814 

• “<sys\stat.h>” on page 819 
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setvbuf — Control Buffering 

Format linclude <stdio.h> 

int setvbuf(FILE *stream, char *buf, int type, size_t size); 

Description Language Level: ANSI, SAA, XPG4 

setvbuf allows control over the buffering strategy and buffer size for a specified 
stream. The stream must refer to a file that has been opened, but not read or written 
to. The array pointed to by buf designates an area that you provide that the C library 
may choose to use as a buffer for the stream. A buf value of NULL indicates that no 
such area is supplied and that the C library is to assume responsibility for managing 
its own buffers for the stream. If you supply a buffer, it must exist until the stream is 
closed. 

The type must be one of the following: 

Value Meaning 

_I ON B F No buffer is used. 

_I0FBF Full buffering is used for input and output. Use buf as the buffer and 

size as the size of the buffer. 

_I0LBF Line buffering is used. The buffer is flushed when a new-line 

character is written, when the buffer is full, or when input is requested. 

If type is _I0FBF or _I0LBF, size is the size of the supplied buffer. If buf is NULL, 
the C library takes size as the suggested size for its own buffer. If type is _I0NBF, 
both buf and size are ignored. 

The value for size must be greater than 0. 

Return Value setvbuf returns 0 if successful. It returns nonzero if an invalid value was specified 
in the parameter list, or if the request cannot be performed. Warning: The array 
used as the buffer must still exist when the specified stream is closed. For example, 
if the buffer is declared within the scope of a function block, the stream must be 
closed before the function is terminated and frees the storage allocated to the buffer. 
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This example sets up a buffer of buf for streaml and specifies that input to stream2 is 
to be unbuffered. 

#include <stdio.h> 

#inc1ude <stdlib.h> 

Idefine BUF_SIZE 1024 

Idefine FILE1 "setvbufl.dat" 

Idefine FILE2 "setvbuf2.dat" 

char buf[BUF_SIZE]; 

FILE *streaml,*stream2; 

int main(void) 

{ 

int flag = EXIT_SUCCESS; 

streaml = fopen(FILEl, “r"); 
stream2 = fopen(FILE2, "r"); 

/* streaml uses a user-assigned buffer of BUF_SIZE bytes */ 

if (setvbuf(streaml, buf, _I0FBF, sizeof(buf)) != G) { 
printf("Incorrect type or size of buffer\n"); 
flag = EXIT_FAILURE; 

} 

/* stream2 is unbuffered */ 

if (setvbuf(stream2, NULL, _I0NBF, 0) != 0) { 
printf("Incorrect type or size of buffer\n"); 
flag = EXIT_FAILURE; 

} 


fclose(streaml); 
fclose(stream2); 
return flag; 

} 

• “fclose — Close Stream” on page 212 

• “ffl ush — Write Buffer to File” on page 224 

• “_f 1 ushal 1 — Write Buffers to Files” on page 240 

• “fopen — Open Files” on page 243 

• “setbuf — Control Buffering” on page 524 

• “<stdio.h>” on page 815 
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signal — 

Format 

Description 


Handle Interrupt Signals 

linclude <signal.h> 

void ( *signal(int sig, void [*sig_handler) (int)) )(int); 

Language Level: ANSI, SAA, XPG4, Extension 

signal function assigns the signal handler sig_handler to handle the interrupt 
signal sig. Signals can be reported as a result of a machine interrupt (for example, 
division by zero) or by an explicit request to report a signal by using the raise 
function. 


The sig argument must be one of the signal constants defined in <signal .h>: 


Value 

SIGABRT 

SIGBREAK 

SIGFPE 


SIGILL 


SIGINT 

SIGSEGV 


SIGTERM 

SIGUSR1 

SIGUSR2 

SIGUSR3 


Meaning 

Abnormal termination signal sent by abort. Default action: end 
the program. 

Ctrl-Break signal. Default action: end the program. 

Floating-point exceptions that are not masked, such as overflow, 
division by zero, and invalid operation. Default action: end the 
program and provide an error message. If machine-state dumps 
are enabled (with the /Tx compiler option), a dump is also 
provided. 

Instruction not allowed. Default action: end the program and 
provide an error message. If machine-state dumps are enabled 
(with the /Tx compiler option), a dump is also provided. 

Ctrl-C signal. Default action: end the program. 

Access to memory not valid. Default action: end the program and 
provide an error message. If machine-state dumps are enabled 
(with the /Tx compiler option), a dump is also provided. 

Program termination signal sent by the user. Default action: end 
the program. 

Defined by the user. Default action: ignore the signal. 

Defined by the user. Default action: ignore the signal. 

Defined by the user. Default action: ignore the signal. 


For sig_handler, you must specify either the SIG_DFL or SIG_IGN constant (also 
defined in <s i g n a 1 .h>), or the address of a function that takes an integer argument 
(the signal). 
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The action taken when the interrupt signal is received depends on the value of 
sig_handler : 

Value Meaning 

SIG_DFL Perform the default action. This is the initial setting for all 

signals. The default actions are described in the list of signals 
above. All files controlled by the process are closed, but buffers 
are not flushed. 


SIG_IGN Ignore the interrupt signal. 

sig_handler Call the function sigjnandler. which you provide, to handle the 
signal specified. 


Your signal handler function ( sig_handler ) must take two integer arguments. The 
first argument is always the signal identifier. The second argument is 0, unless the 
signal is SIG_FPE. For SIG_FPE signals, the second argument passed is a 
floating-point error signal as defined in <float.h>. If your sig_handler returns, the 
calling process resumes running immediately following the point at which it received 
the interrupt signal. 


After a signal is reported and the sig_handler is called, signal handling for that 
signal is reset to the default. Depending on the purpose of the signal handler, you 
may want to call signal inside sig_handler to reestablish sig_handler as the 
signal handler. You can also reset the default handling at any time by calling signal 
and specifying SIG_DFF. 

Signals and signal handlers are not shared between threads. If you do not establish a 
handler for a specific signal within a thread, the default signal handling is used 
regardless of what handlers you may have established in other concurrent threads. 

Note: If an exception occurs in a math or critical library function, it is handled by 
the VisualAge C++ exception handler. Your sig_handler will not be called. For 
more information about signals and exceptions, refer to Signal and OS/2 Exception 
Handling in the Programming Guide. 


Return Value All calls to signal return the address of the previous handler for the re-assigned 
signal. 

A return value of SIG_ERR (defined in <signal ,h>) indicates an error, and errno is 
set to EINVAF. The possible causes of the error are an incorrect sig value or an 
undefined value for sig_handler. 
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In the following example, the call to signal in main establishes the function handler 
to process the interrupt signal raised by abort. The handler prints a message and 
returns to the system. 

#define INCL_DOSFILEMGR 
#include <os2,h> 

#include <signal.h> 
linclude <stdio.h> 

#include <stdlib.h> 

#include <string.h> 


void handler(int sig) 

{ 

UCHAR Fi1eData[100] ; 
ULONG Wrote; 


strcpy(Fi1eData, "Signal occurred.\n\r"); 

DosWrite(2, (PVOID)Fi1eData, strlen(FileData), &Wrote); 


int main(void) 

{ 

if (SIG_ERR == signal(SIGABRT, handler)) { 
perror("Could not set SIGABRT"); 
return EXIT_FAILURE; 

} 

abort(); /* signal raised by abort */ 

return 0; /* code should not reach here */ 

/**************************************************************************** 

The output should be: 


Signal occurred. 


} 


/ 



“abort — Stop a Program” on page 47 

“atexit — Record Program Termination Function” on page 62 

“exit — End Program” on page 204 

“_exi t — End Process” on page 205 

“_fpreset — Reset Floating-Point Unit” on page 247 

“raise — Send Signal” on page 480 

“_spawnl - _spawnvpe — Start and Run Child Processes” on page 548 
Signal and OS/2 Exception Handling in the Programming Guide 
“<signal.h>” on page 814 


542 VisualAge C++ C Library Reference 




sin — Calculate Sine 


Format 

Description 

Return Value 



linclude <math.h> 
double sin(double x ); 

Language Level: ANSI, SAA, POSIX, XPG4 

sin calculates the sine of x, with x expressed in radians. If x is too large, a partial 
loss of significance in the result may occur. 

sin returns the value of the sine of x. 

This example computes y as the sine of jt/2. 

#include <math.h> 

int main(void) 

{ 

double pi,x,y; 

pi = 3.1415926535; 
x = pi/2; 
y = sin(x); 

printf("sin( %lf ) = x, y); 

return 0; 

/**************************************************************************** 

The output should be: 

sin( 1.570796 ) = 1.000000 

****************************************************************************/ 

} 

• “asi n — Calculate Arcsine” on page 57 

• “cos — Calculate Cosine” on page 111 

• “_fasin — Calculate Arcsine” on page 210 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsin — Calculate Sine” on page 277 

• “_fsi ncos — Calculate Sine and Cosine” on page 278 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “<math.h>” on page 811 
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sinh — Calculate Hyperbolic Sine 

Format linclude <math.h> 

double sinh(double x) ; 

Description Language Level: ANSI, SAA, POSIX, XPG4 

sinh calculates the hyperbolic sine of x, with x expressed in radians. 

Return Value sinh returns the value of the hyperbolic sine of x. If the result is too large, sinh 

sets errno to ERANGE and returns the value HUGE_VAL (positive or negative, depending 
on the value of x ). 

This example computes y as the hyperbolic sine of jt/2. 
linclude <math.h> 

int main(void) 

{ 

double pi,x,y; 

pi = 3.1415926535; 
x = pi/2; 
y = sinh(x); 

printf ("sinh( %lf ) = %lf\n\ x, y); 
return 0; 

I *■******************'************'************'**'**'********'**********'*'*'*'***'****'* 

The output should be: 

sinh( 1.570796 ) = 2.301299 

} 

• “asin — Calculate Arcsine” on page 57 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_fasin — Calculate Arcsine” on page 210 

• “_fcossin — Calculate Cosine and Sine” on page 215 

• “_fsi n — Calculate Sine” on page 277 

• “_fsincos — Calculate Sine and Cosine” on page 278 

• “sin — Calculate Sine” on page 543 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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_sopen — 

Format 

Description 


Open Shared File 

#include <fcntl.h> 
linclude <sys\stat.h> 
linclude <share.h> 
linclude <io.h> 

int _sopen(char *pathname, int of lag , int shflag , int pmode ); 


Language Level: Extension 


_Sopen opens the file specified by pathname and prepares the file for subsequent 
shared reading or writing as defined by of lag and shflag. The oflag is an integer 
expression formed by combining one or more of the constants defined in <fcntl .h>. 
When more than one constant is given, the constants are joined with the OR operator 

(I). 


Oflag 

0_APPEND 

0_CREAT 

0_EXCL 

0_RD0NLY 

0_RDWR 

OJTRUNC 

0_WR0NLY 

0_BINARY 

0_TEXT 


Meaning 

Reposition the file pointer to the end of the file before every write 
operation. 

Create and open a new file. This flag has no effect if the file 
specified by pathname exists. 

Return an error value if the file specified by pathname exists. This 
flag applies only when used with 0_CREAT. 

Open the file for reading only. If this flag is given, neither 
0_RDWR nor 0_WR0NLY can be given. 

Open the file for both reading and writing. If this flag is given, 
neither 0_RD0NLY nor 0_WR0NLY can be given. 

Open and truncate an existing file to 0 length. The file must have 
write permission. The contents of the file are destroyed. On the 
OS/2 operating system, do not specify 0_TRUNC with 
0_RD0NLY. 

Open the file for writing only. If this flag is given, neither 
0_RD0NLY nor 0_RDWR can be given. 

Open the file in binary (untranslated) mode. 

Open the file in text (translated) mode. (See “Stream Processing” 
in the Programming Guide for a description of text and binary 
mode.) 


The shflag argument is one of the following constants, defined in <share.h>: 


Shflag 

SH_DENYRW 

SH_DENYWR 

SH_DENYRD 

SH_DENYNO 


Meaning 

Deny read and write access to file. 
Deny write access to file. 

Deny read access to file. 

Permit read and write access. 
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Return Value 



There is no default value for the shflag. 

The pmode argument is required only when you specify 0_CREAT. If the file does 
not exist, pmode specifies the permission settings of the file, which are set when the 
new file is closed for the first time. If the file exists, the value of pmode is ignored. 
The pmode must be one of the following values, defined in <sys\stat.h>: 

Value Meaning 

SIWRITE Writing permitted 

S_IREAD Reading permitted 

S_IREAD I S IWRITE Reading and writing permitted. 

If write permission is not given, the file is read-only. On the OS/2 operating system, 
all files are readable; you cannot give write-only permission. Thus, the modes 
S_IWRITE and S_IREAD I S_IWRITE are equivalent. Specifying a pmode of 
S_IREAD is similar to making a file read-only with the ATTRIB system command. 

_sopen applies the current file permission mask to pmode before setting the 
permissions. (See “umask — Sets File Mask of Current Process” on page 719 for 
information on file permission masks.) 


_SOpen returns a file handle for the opened file. A return value of -1 indicates an 
error, and errno is set to one of the following values: 


Value 

EACCESS 


EEXIST 

EMFILE 

ENOENT 

EINVAL 

EOS2ERR 


Meaning 

The given path name is a directory, but the file is read-only and at 
attempt was made to open if for writing, or a sharing violation 
occurred. 

The 0_CREAT and 0_EXCL flags are specified, but the named file 
already exists. 

No more file handles are available. 

The file or path name was not found. 

An incorrect argument was passed. 

The call to the operating system was not successful. 


This example opens the file sopen.dat for shared reading and writing using _sopen. 
It then opens the file for shared reading. 
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#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl.h> 
line!ude <share.h> 

Idefine FILENAME "sopen.dat" 

int main(void) 

{ 

int fhl,fh2; 

printf("Creating fi1e.\n"); 
system("echo Sample Program > " FILENAME); 

/* share open the file for reading and writing */ 

if (-1 == (fhl = _sopen(FILENAME, 0_RDWR, SH_DENYN0))) { 
perrorfsopen failed"); 
remove(FILENAME); 
return EXIT_FAILURE; 

} 

/* share open the file for reading only */ 

if (-1 == (fh2 = _sopen(FILENAME, 0_RD0NLY, SH_DENYN0))) { 
perror("sopen failed"); 
close(fhl); 
remove(FILENAME); 
return EXIT_FAILURE; 

} 

printf("Fi1e successfully opened for sharing.\n"); 

cl ose(fhl); 

close(fh2); 

remove(FILENAME); 

return 0; 

/**************************************************************************** 
The output should be: 

Creating file. 

File successfully opened for sharing. 

****************************************************************************/ 

} 


• “close — Close File Associated with Handle” on page 99 

• “creat — Create New File” on page 115 

• “open — Open File” on page 447 

• “fdopen — Associates Input Or Output With File” on page 219 

• “fopen — Open Files” on page 243 

• “_sopen — Open Shared File” on page 545 

• “umask — Sets File Mask of Current Process” on page 719 

• “<fcntl.h>” on page 803 

• “<io.h>” on page 804 

• “<share.h>” on page 814 

• “<sys\stat.h>” on page 819 
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_spawnl - 

Format 


Description 


spawnvpe — Start and Run Child Processes 

linclude <process.h> 

int _spawnl(int modeflag, char *pathname, char *argO, char *argl . 

char *argn, NULL); 

int _spawnlp(int modeflag, char * pathname , char *argO, char *argl, ..., 
char *argn, NULL); 

int _spawnle(int modeflag, char * pathname , char *argO, char *argl, ..., 
char *argn, NULL, char *envp[ ]); 

int _spawnlpe(int modeflag, char *pathname, char *argO, char *argl, ..., 
char *argn, NULL, char *envp[ ]); 

int _spawnv(int modeflag, char *pathname, char *argv[ ]); 

int _spawnvp(int modeflag, char * pathname , char *argv[ ]); 

int _spawnve(int modeflag, char * pathname , char *argv[ ], char *envp[ ]); 

int _spawnvpe(int modeflag, char *pathname, char *argv\ ], char *envp[ ]) 


Language Level: Extension 


Each of the _spawn functions creates and runs a new child process. Enough storage 
must be available for loading and running the child process. All of the _spawn 
functions are versions of the same routine; the letters at the end determine the specific 
variation: 

Letter Variation 

p Uses PATH environment variable to find the file to be run 

1 Lists command-line arguments separately 

v Passes to the child process an array of pointers to command-line 

arguments 

e Passes to the child process an array of pointers to environment strings. 


The modeflag argument determines the action taken by the parent process before and 
during the _spawn. The values for modeflag are defined in <process.h>: 


Value 

P_WAIT 

P_NOWAIT 

P_OVERLAY 


Meaning 

Suspend the parent process until the child process is complete. 
Continue to run the parent process concurrently. 

Start the child process, and then, if successful, end the parent 
process. (This has the same effect as exec calls.) 


The pathname argument specifies the file to run as the child process. The pathname 
can specify a full path (from the root), a partial path (from the current working 
directory), or just a file name. If pathname does not have a file-name extension or 
end with a period, the _spawn functions add the extension .EXE and search for the 
file. If pathname has an extension, only that extension is used. If pathname ends 
with a period, the _spawn functions search for pathname with no extension. The 
_spawnlp, _spawnlpe, _spawnvp, and _spawnvpe functions search for pathname 


548 


VisualAge C++ C Library Reference 



spawnl - _spawnvpe 


(using the same procedures) in the directories specified by the PATH environment 
variable. 

You pass arguments to the child process by giving one or more pointers to character 
strings as arguments in the _spawn routine. These character strings form the 
argument list for the child process. 

The argument pointers can be passed as separate arguments (_spawnl, _spawnle, 
_spawnlp, and _spawnlpe) or as an array of pointers (_spawnv, _spawnve, _spawnvp, 
and _spawnvpe). At least one argument, either argQ or argv[0], must be passed to 
the child process. By convention, this argument is a copy of the pathname argument. 
However, a different value will not produce an error. 

Use the _spawnl, _spawnle, _spawnlp, and _spawnlpe functions where you know 
the number of arguments. The argO is usually a pointer to pathname. The argl 
through argn arguments are pointers to the character strings forming the new 
argument list. Following argn, a NULL pointer must mark the end of the argument list. 

The _spawnv, _spawnve, _spawnvp, and _spawnvpe functions are useful when the 
number of arguments to the child process is variable. Pointers to the arguments are 
passed as an array, argv. The argv[0] argument is usually a pointer to the pathname. 
The argv[l] through argv[n] arguments are pointers to the character strings forming 
the new argument list. The argv[n+l] argument must be a NULL pointer to mark the 
end of the argument list. 

Files that are open when a _spawn call is made remain open in the child process. In 
the _spawnl, _spawnlp, _spawnv, and _spawnvp calls, the child process inherits the 
environment of the parent. The _spawnle, _spawnlpe, _spawnve, and _spawnvpe 
functions let you alter the environment for the child process by passing a list of 
environment settings through the envp argument. The envp argument is an array of 
character pointers, each element of which points to a null-terminated string, that 
defines an environment variable. Such a string has the form: 

NAME=value 

where NAME is the name of an environment variable, and value is the string value to 
which that variable is set. (Notice that value is not enclosed in double quotation 
marks.) The final element of the envp array should be NULL. When envp itself is 
NULL, the child process inherits the environment settings of the parent process. 

Note: Signal settings are not preserved in child processes created by calls to _spawn 
functions. The signal settings are reset to the default in the child process. 
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Return Value 



The return from a spawn function has one of two different meanings. The return 
value of a synchronous spawn is the exit status of the child process. The return value 
of an asynchronous spawn is the process identification of the child process. You can 
use wait or _cwait to get the child process exit code if an asynchronous spawn was 
done. 


A return value of -1 indicates an error (the child process is not started), and errno is 
set to one of the following values: 


Value 

EAGAIN 

EINVAL 

ENOENT 

ENOEXEC 

ENOMEM 


Meaning 

The limit of the number of processes that the operating system permits 
has been reached. 

The modeflag argument is incorrect. 

The file or path name was not found or was not specified correctly. 
The specified file is not executable or has an incorrect executable file 
format. 

Not enough storage is available to run the child process. 


This example calls four of the eight _spawn routines. When called without arguments 
from the command line, the program first runs the code for case PARENT. It spawns 
a copy of itself, waits for its child process to run, and then spawns a second child 
process. The instructions for the child process are blocked to run only if argv [0] and 
one parameter were passed (case CHILD). In its turn, each child process spawns a 
grandchild as a copy of the same program. The grandchild instructions are blocked 
by the existence of two passed parameters. The grandchild process can overlay the 
child process. Each of the processes prints a message identifying itself. 

#include <stdio.h> 
linclude <process.h> 

#define PARENT 1 

#define CHILD 2 

#define GRANDCHILD 3 

int main(int argc.char **argv,char **envp) 

{ 

int result; 
char *args[4]; 
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switch (argc) { 

case PARENT : /* no argument was passed: spawn child and wait */ 

result = _spawnle(P_WAIT, argv[0], argv[0], "one", NULL, envp); 
if (result) 
abort(); 

args[0] = argv[0]; 
args[l] = "two"; 
args[2] = NULL; 

/* spawn another child, and wait for it */ 

result = _spawnve(P_WAIT, argv[0], args, envp); 
if (result) 
abort(); 

printf("Parent process ended\n"); 
exit(O); 


case CHILD : /* one argument passed: allow grandchild to overlay */ 

printf("chi 1d process %s began\n", argv[l]); 

if ('o' == *argv[l]) /* child one? */ 

{ 

_spawnl(P_0VERLAY, argv[Q], argv[0], "one", "two", NULL); 
abort(); /* not executed because child was overlaid */ 

} 

if ('t' ='= *argv[l]) /* child two? */ 


{ 

args[0] = argv[0]; 
args[l] = "two"; 
args[2] = "one"; 
args[3] = NULL; 

_spawnv(P_OVERLAY, argv[0], args); 

abort(); /* not executed because child was overlaid */ 

} 

abort(); /* argument not valid */ 

case GRANDCHILD : /* two arguments passed */ 

printf("grandchi1d %s ran\n", argv[l]); 
exit(O); 

} 

/**************************************************************************** 
The output should be: 

child process one began 
grandchild one ran 
child process two began 
grandchild two ran 
Parent process ended 

****************************************************************************/ 


• “abort — Stop a Program” on page 47 

• “_cwai t — Wait for Child Process” on page 131 

• “execl - _execvpe — Load and Run Child Process” on page 200 

• “exi t — End Program” on page 204 

• “_exit — End Process” on page 205 

• “<process.h>” on page 812 
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splitpath — Decompose Path Name 

Format linclude <stdlib.h> 

void _splitpath(char *path, char *drive, char *dir, 
char *fname, char *ext ); 

Description Language Level: Extension 

_spl i tpath decomposes an existing path name path into its four components. The 
path should point to a buffer containing the complete path name. 

The maximum size necessary for each buffer is specified by the _MAX_DRIVE, 
_MAX_DIR, _MAX_FNAME, and _MAX_EXT constants defined in <stdlib.h>. 

The other arguments point to the following buffers used to store the path name 
elements: 

Buffer Description 

drive Contains the drive letter followed by a colon (:) if a drive is specified in 
path. 

dir Contains the path of subdirectories, if any, including the trailing slash. 

Slashes (/), backslashes (\), or both may be present in path, 
frame Contains the base file name without any extensions. 

ext Contains the file name extension, if any, including the leading period (.). 

You can specify NULL for any of the buffer pointers to indicate that you do not want 
the string for that component returned. 

The return parameters contain empty strings for any path name components not found 
in path. 

Return Value There is no return value. 
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This example builds a file name path from the specified components, and then 
extracts the individual components. 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

char path_buffer[_MAX_PATH]; 
char drive[_MAX_DRIVE]; 
char dir[_MAX_DIR]; 
char fname[_MAX_FNAME]; 
char ext[_MAX_EXT]; 

_makepath(path_buffer, "c", "qcWbobWecl ibrefWe", "makepath", "c"); 
printf("Path created with _makepath: %s\n\n", path_buffer); 

_splitpath(path_buffer, drive, dir, fname, ext); 

printf("Path extracted with _splitpath:\n"); 

printf("drive: %s\n", drive); 

printf("directory: %s\n", dir); 

printf("fi1e name: %s\n", fname); 

printf("extension: %s\n", ext); 

return 0; 

/**************************************************************************** 
The output should be: 

Path created with _makepath: c:qc\bob\eclibref\e\makepath.c 

Path extracted with _sp1itpath: 
drive: c: 

directory: qc\bob\eclibref\e\ 
file name: makepath 
extension: .c 

****************************************************************************/ 


• “_ful 1 path — Get Full Path Name of Partial Path” on page 287 

• “_getcwd — Get Path Name of Current Directory” on page 300 

• “_getdcwd — Get Full Path Name of Current Directory” on page 302 

• “_makepath — Create Path” on page 401 

• “<stdlib.h>” on page 816 
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sprintf — Print Formatted Data to Buffer 

Format linclude <stdio.h> 

int sprintf(char *buffer, const char *format-string, argument-list ); 

Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

sprintf formats and stores a series of characters and values in the array buffer. 

Any argument-list is converted and put out according to the corresponding format 
specification in the format-string. 

The format-string consists of ordinary characters and has the same form and 
function as the format-string argument for the printf function. See “pri ntf — 
Print Formatted Characters” on page 461 for a description of the format-string and 
arguments. 

In extended mode, sprintf also converts floating-point values of NaN and infinity to 
the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 

If you specify a null string for the %s or %ls format specifier, sprintf prints (null). 
(In previous releases of C Set ++, sprintf produced no output for a null string.) 

Return Value sprintf returns the number of bytes written in the array, not counting the ending 
null character. 

This example uses sprintf to format and print various data. 

linclude <stdio.h> 

char buffer[200]; 
int i,j; 
double fp; 

char *s = "baltimore"; 
char c; 
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int main(void) 

{ 

c = 1 1 1 ; 
i = 35; 

fp = 1.7320508; 

/* Format and print various data */ 

j = sprintf(buffer, "%s\n", s); 
j += sprintf(buffer+j, "%c\n", c); 
j += sprintf(buffer+j, "%d\n", i); 
j += sprintf(buffer+j, "%f\n", fp); 

printf("string:\n%s\ncharacter count = %d\n", buffer, j); 
return 0; 

/**************************************************************************** 

The output should be: 

string: 

baltimore 

1 

35 

1.732051 

character count = 24 

****************************************************************************/ 

} 


• “Infinity and NaN Support” on page 33 

• “_cprintf — Print Characters to Screen” on page 113 

• “fpri ntf — Write Formatted Data to a Stream” on page 249 

• “pri ntf — Print Formatted Characters” on page 461 

• “sscanf — Read Data” on page 559 

• “swprintf — Format and Write Wide Characters to Buffer” on page 635 

• “vfprintf — Print Argument Data to Stream” on page 739 

• “vpri ntf — Print Argument Data” on page 741 

• “vsprintf — Print Argument Data to Buffer” on page 743 

• “vswprintf — Format and Write Wide Characters to Buffer” on page 745 

• “<stdio.h>” on page 815 
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sqrt — Calculate Square Root 

Format linclude <math.h> 

double sqrt(double x) ; 

Description Language Level: ANSI, SAA SAA, POSIX, XPG4 

sqrt calculates the nonnegative value of the square root of x. 

Return Value sqrt returns the square root result. If x is negative, the function sets errno to EDOM, 
and returns 0. 

This example computes the square root of the quantity passed as the first argument to 
main. It prints an error message if you pass a negative value. 

linclude <stdio.h> 
linclude <stdlib.h> 
linclude <math.h> 

int main(int argc.char **argv) 

{ 

double value = 45.0; 

printf("sqrt( %f ) = %f\n", value, sqrt(value)); 
return 0; 

/•k-k-klt-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-kitle-k-k-k-k-k-k-k-kle-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k 

The output should be: 
sqrt( 45.000000 ) = 6.708204 

■k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-kick-kit/ 

} 

• “exp — Calculate Exponential Function” on page 206 

• “_fsqrt — Calculate Square Root” on page 280 

• “hypot — Calculate Hypotenuse” on page 333 

• “1 og — Calculate Natural Logarithm” on page 387 

• “log 10 — Calculate Base 10 Logarithm” on page 388 

• “pow — Compute Power” on page 460 

• “<math.h>” on page 811 
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srand — Set Seed for rand Function 

Format linclude <stdlib.h> 

void srand(unsigned int seed); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

srand sets the starting point for producing a series of pseudo-random integers. If 
srand is not called, the rand seed is set as if srand(l) were called at program start. 
Any other value for seed sets the generator to a different starting point. 

The rand function generates the pseudo-random numbers. 

Return Value There is no return value. 

This example first calls srand with a value other than 1 to initiate the random value 
sequence. Then the program computes five random values for the array of integers 
called ranvals. 

#inc1ude <stdlib.h> 

#inc1ude <stdio.h> 

int main(void) 

{ 

i nt i,ranvals[5]; 
srand(17); 

for (i = 0; i < 5; i++) { 
ranvals [i] = rand(); 

printf("Iteration %d ranvals [%d] = %d\n", i+1, i, ranvals[i]); 

} 

return 0; 

/**************************************************************************** 

The output should be similar to: 

Iteration 1 ranvals [0] = 24107 
Iteration 2 ranvals [1] = 16552 
Iteration 3 ranvals [2] = 12125 
Iteration 4 ranvals [3] = 9427 
Iteration 5 ranvals [4] = 13152 

****************************************************************************/ 

} 

• “rand — Generate Random Number” on page 481 

• “<stdlib.h>” on page 816 
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srotl - srotr — Rotate Bits of Unsigned Short Value 

linclude <stdlib.h> /* also in <builtin.h> */ 

unsigned short _srotl(unsigned short value, int shift); 
unsigned short _srotr(unsigned short value, int shift); 

Description Language Level: Extension 

The _srotl and _srotr functions rotate the unsigned short integer value by shift 
bits. The _srotl function rotates to the left, and _srotr to the right. 

Note: Both _srotl and _srotr are built-in functions, which means they are 

implemented as inline instructions and have no backing code in the library. 
For this reason: 

• You cannot take the address of these functions. 

• You cannot parenthesize a call to either function. (Parentheses specify a 
call to the function's backing code, and these functions have none.) 

Return Value Both functions return the rotated value. There is no error return value. 

This example uses _srotl and _srotr with different shift values to rotate the 
character value: 

linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

unsigned short val = 0X0123; 

printf("The value of 0x%4.4x rotated 4 bits to the left is 0x%4.4x\n", val, 

_srotl(val, 4)); 

printf("The value of 0x%4.4x rotated 8 bits to the right is 0x%4.4x\n", 
val, _srotr(val, 8)); 
return 0; 

/**************************************************************************** 

The output should be: 

The value of 0x0123 rotated 4 bits to the left is 0x1230 
The value of 0x0123 rotated 8 bits to the right is 0x2301 
****************************************************************************/ 

} 

• “_crotl - _crotr — Rotate Bits of Character Value” on page 117 

• “_1 rotl - _1 rotr — Rotate Bits of Unsigned Long Value” on page 392 

• “_rotl - _rotr — Rotate Bits of Unsigned Integer” on page 514 

• “<stdlib.h>” on page 816 

• “<builtin.h>” on page 801 
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sscanf — Read Data 


Format linclude <stdio.h> 

int sscanf(const char *buffer, const char *format, argument-list); 


Description Language Level: ANSI, SAA, POSIX, XPG4, Extension 

sscanf reads data from buffer into the locations given by argument-list. Each 
argument must be a pointer to a variable with a type that corresponds to a type 
specifier in the format-string. See “scanf — Read Data” on page 517 for a 
description of the format-string. 


Return Value sscanf returns the number of fields that were successfully converted and assigned. 
The return value does not include fields that were read but not assigned. 

The return value is EOF when the end of the string is encountered before anything is 
converted. 



This example uses sscanf to read various data from the string tokenstring , and then 
displays that data. 

#include <stdio.h> 


Idefine SIZE 81 


char *tokenstring = "15 12 14"; 

i nt i; 

float fp; 

char s [SIZE]; 

char c; 

int main(void) 

{ 


/* Input various data */ 
sscanf(tokenstring, "%s %c%d%f", s. Sc, &i, &fp); 

/* If there were no space between %s and %c, */ 
/* sscanf would read the first character following */ 
/* the string, which is a blank space. */ 
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/* Display the data */ 

printf("string = %s\n", s); 
printf("character = %c\n", c); 
printf("integer = %d\n", i); 
printf("floating-point number = %f\n", fp); 
return 0; 

/**************************************************************************** 

The output should be: 

string = 15 
character = 1 
integer = 2 

floating-point number = 14.000000 

****************************************************************************/ 

} 


/***************** Output should be similar to: ***************** 

string = 15 
character = 1 
integer = 2 

floating-point number = 14.000000 
*/ 



“Infinity and NaN Support” on page 33 

“_cscanf — Read Data from Keyboard” on page 127 

“fscanf — Read Formatted Data” on page 271 

“scanf — Read Data” on page 517 

“spri ntf — Print Formatted Data to Buffer” on page 554 

“swscanf — Read Wide Characters from Buffer” on page 637 

“<stdio.h>” on page 815 
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stat — Get Information about File or Directory 

Format finclude <sys\types.h> 

finclude <sys\stat.h> 

int stat (const char * pathname , struct stat * buffer ) 


Description Language Level: XPG4, Extension 


stat stores information about the file or directory specified by pathname in the 
structure to which buffer points. The stat structure, defined in <sys\stat.h>, 
contains the following fields: 

Field Value 

stjnode Bit mask for file-mode information, stat sets the S_IFCHR bit if 

handle refers to a device. The S_IFDIR bit is set if pathname 
specifies a directory. The S_IFREG bit is set if pathname specifies 
an ordinary file. User read/write bits are set according to the 
permission mode of the file. The S_IEXEC bit is set using the file 
name extension. The other bits are undefined. 


SJFREG 
(regular file) 
SJFDIR 
S IFCHR 


FEDCBA987654321 0 



st_dev Drive number of the disk containing the file. 

st_rdev Drive number of the disk containing the file (same as st_dev). 

st_nl ink Always 1. 

st_size Size of the file in bytes. 

st_atime Time of last access of file. 

stjntime Time of last modification of file. 

st_ctime Time of file creation. 

Note: If the given pathname specifies only a device (for example C:\), stat returns 
an error, and fields in the stat structure are not meaningful. 
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stat 


Note: In earlier releases of C Set ++, stat began with an underscore (_stat). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _stat to stat for you. 


Return Value stat returns the value 0 if the file status information is obtained. A return value of 
-1 indicates an error, and errno is set to ENOENT, indicating that the file name or 
path name could not be found. 



This example requests that the status information for the file test.exe be placed into 
the structure buf. If the request is successful and the file is executable, the example 
runs test.exe. 

linclude <sys\types.h> 
linclude <sys\stat.h> 
linclude <process.h> 

#include <stdio.h> 


int main(void) 

{ 

struct stat buf; 

if (0 =« stat("test.exe", &buf)) { 

if ((buf.st_mode&S_IFREG) && (buf.st_mode&S_IEXEC)) 

execl("test.exe", "test", NULL); /* file is executable */ 


else 

printf("File could not be found\n"); 
return 0; 

/**************************************************************************** 

The source for test.exe is: 

#include <stdio.h> 
int main(void) 

{ 

puts("test.exe is an executable file"); 

} 



The output should be: 
test.exe is an executable file 

■k-k-k-k-k-k-kie-k-k-k-k-klc-k-k'k-k-kit-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-kick-k-k-kick-k-k'k-k-kick-k-k-k-k'k-k-k/ 

} 

• “fstat — Information about Open File” on page 281 

• “<sys\stat.h>” on page 819 

• “<sys\types.h>” on page 819 
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_status87 - 

Format 

Description 

Return Value 



Get Floating-Point Status Word 

linclude <float.h> /* also in <builtin.h> */ 
unsigned int _status87(void); 

Language Level: Extension 

_status87 gets the current floating-point status word. The floating-point status word 
is a combination of the numeric coprocessor status word and other conditions detected 
by the numeric exception handler, such as floating-point stack underflow and 
overflow. 

The bits in the value returned reflect the floating-point status for the current thread 
only before the call was made. _status87 does not affect any other threads that may 
be processing. 

This example uses _status87 to get the value of the floating-point status word. 

#include <stdio.h> 

#include <float.h> 

double a = le-40,b; 
float x,y; 

int main(void) 

{ 

printf("status = 0x%.4x - clear\n", _status87()); 

/* change control word to mask all exceptions */ 

_control87(0x037f, Oxffff); 

y = a; /* store into y is inexact and causes underflow */ 

printf("status = 0x%.4X - inexact, underflow\n", _status87()); 

/* reinitialize the floating point unit */ 

_fpreset(); 

/* change control word to mask all exceptions */ 

_control87(0x037f, Oxffff); 

b = y; /* y is denormal */ 

printf("status = 0x%.4X - denormal\n", _status87()); 

/* reinitialize the floating point unit */ 

_fpreset(); 
return 0; 
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/**************************************************************************** 

The output should be: 

status = 0x0000 - clear 

status = 0x0030 - inexact, underflow 

status = 0x0002 - denormal 

****************************************************************************/ 

} 


“_cl ear87 — Clear Floating-Point Status Word” on page 95 
“_control87 — Set Floating-Point Control Word” on page 109 
“_fpreset — Reset Floating-Point Unit” on page 247 
“<float.h>” on page 803 
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strcat — Concatenate Strings 

Format linclude <string.h> 

char *strcat(char *stringl, const char *string2 ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strcat concatenates string2 to stringl and ends the resulting string with the null 
character. 


strcat operates on null-terminated strings. The string arguments to the function 
should contain a null character (\Q) marking the end of the string. No length 
checking is performed. You should not use a literal string for a stringl value, 
although string2 may be a literal string. 

If the storage of stringl overlaps the storage of string2 , the behavior is undefined. 


Return Value strcat returns a pointer to the concatenated string (stringl). 



This example creates the string "computer program" using strcat. 

#include <stdio.h> 

#inc1ude <string.h> 

Idefine SIZE 40 


int main(void) 

{ 

char bufferl[SIZE] = "computer"; 
char *ptr; 

ptr = strcat(bufferl, " program"); 
printf("bufferl = %s\n", bufferl); 
return 0; 


/**************************************************************************** 
The output should be: 

bufferl = computer program 

****************************************************************************/ 

i 



“strchr — Search for Character” on page 566 

“strcmp — Compare Strings” on page 567 

“strcpy — Copy Strings” on page 573 

“strcspn — Compare Strings for Substrings” on page 575 

“strncat — Concatenate Strings” on page 595 

“wcscat — Concatenate Wide-Character Strings” on page 749 

“wcsncat — Concatenate Wide-Character Strings” on page 764 

“<string.h>” on page 818 
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strchr — Search for Character 

Format linclude <string.h> 

char *strchr(const char * string, int c); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strchr finds the first occurrence of a character in a string. The character c can be the 
null character (\0); the ending null character of string is included in the search. 

The strchr function operates on null-terminated strings. The string arguments to the 
function should contain a null character (\0) marking the end of the string. 

Return Value strchr returns a pointer to the first occurrence of c converted to a character in 
string. The function returns NULL if the specified character is not found. 

This example finds the first occurrence of the character p in "computer program". 

linclude <stdio.h> 
linclude <string.h> 

Idefine SIZE 40 

int main(void) 

{ 

char bufferl[SIZE] = "computer program"; 
char *ptr; 
int ch = 'p'; 

ptr = strchr(bufferl, ch); 

printf("The first occurrence of %c in '%s 1 is ’%s'\n", ch, bufferl, ptr); 
return 0; 

/•k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k'k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k1<1c-kic-k-k1<‘k-k-k1e-k-k‘k-k-k‘k-k-k‘k'k-k‘k-k-k‘k-k-k‘k-k-k‘k 

The output should be: 

The first occurrence of p in 'computer program 1 is 'puter program 1 

ici(-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k-k-k-k-k-k-k‘k-ki<‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k'k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k-k-k-k‘k-ki(^ 

} 

• “strcmp — Compare Strings” on page 567 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strncmp — Compare Strings” on page 597 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcsspn — Search Wide-Character Strings” on page 776 

• “<string.h>” on page 818 
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strcmp — Compare Strings 

Format linclude <string.h> 

int strcmp(const char *stringl, const char *string2 ); 


Description Language Level: ANSI, SAA, POSIX, XPG4 

strcmp compares stringl and string2. The function operates on null-terminated 
strings. The string arguments to the function should contain a null character (\0) 
marking the end of the string. 


Return Value strcmp returns a value indicating the relationship between the two strings, as 
follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

stringl less than string2 
stringl identical to string2 
stringl greater than string2. 



This example compares the two strings passed to main using strcmp. 

#inc1ude <stdio.h> 

#include <string.h> 

int main(int argc.char **argv) 

{ 

int result; 


if (argc != 3) { 

printf("Usage: %s stringl string2\n", argv[0]); 

} 

el se { 

result = strcmp(argv[l], argv[2]); 
if (0 == result) 

printf("\"%s\" is identical to \"%s\"\n", argv[l], argv[2]); 
el se 

if (result < 0) 

printf("\"%s\" is less than \"%s\"\n", argv[l], argv[2]); 
el se 

printf("\"%s\" is greater than \"%s\"\n", argv[l], argv[2]); 


return 0; 

/**************************************************************************** 
If the following arguments are passed to this program: 

"is this first?" "is this before that one?" 

The output should be: 

"is this first?" is greater than "is this before that one?" 
****************************************************************************/ 

} 
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“strcmpi — Compare Strings Without Case Sensitivity” on page 569 
“strcol 1 — Compare Strings Using Collation Rules” on page 571 
“strcspn — Compare Strings for Substrings” on page 575 
“stri cmp — Compare Strings as Lowercase” on page 591 
“strncmp — Compare Strings” on page 597 

“strni cmp — Compare Strings Without Case Sensitivity” on page 601 
“wcscmp — Compare Wide-Character Strings” on page 752 
“wcsncmp — Compare Wide-Character Strings” on page 766 
“<string.h>” on page 818 
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strcmpi — Compare Strings Without Case Sensitivity 

Format linclude <string.h> 

int strcmpi(const char *stringl, const char *string2 ); 


Description Language Level: Extension 

strcmpi compares stringl and string2 without sensitivity to case. All alphabetic 
characters in the two arguments stringl and string2 are converted to lowercase 
before the comparison. 

The function operates on null-ended strings. The string arguments to the function are 
expected to contain a null character (\0) marking the end of the string. 


Return Value strcmpi returns a value indicating the relationship between the two strings, as 
follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

stringl less than string2 
stringl equivalent to string2 
stringl greater than string2. 



This example uses strcmpi to compare two strings. 

#inc1ude <stdio.h> 

#include <string.h> 

int main(void) 

{ 



/* Compare two strings without regard to case */ 

if (0 == strcmpi("hello", "HELLO")) 

printf("The strings are equivalent.\n"); 
el se 

printf("The strings are not equivalent.\n"); 
return 0; 

/**************************************************************************** 
The output should be: 

The strings are equivalent. 

****************************************************************************/ 

i 

• “strcoll — Compare Strings Using Collation Rules” on page 571 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strdup — Duplicate String” on page 578 

• “stri cmp — Compare Strings as Lowercase” on page 591 

• “strncmp — Compare Strings” on page 597 

• “strnicmp — Compare Strings Without Case Sensitivity” on page 601 
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• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcsncmp — Compare Wide-Character Strings” on page 766 

• “<string.h>” on page 818 
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strcoll — Compare Strings Using Collation Rules 

Format linclude <string.h> 

int strcol1(const char *stringl, const char *string2 ); 

Description Language Level: ANSI, SAA, XPG4 

strcol 1 compares the string pointed to by stringl against the string pointed to by 
string2, both interpreted according to the information in the LC_COLLATE 
category of the current locale. 

strcol 1 differs from the strcmp function, strcol 1 performs a comparison between 
two character strings based on language collation rules as controlled by the 
LC_COLLATE category. In contrast, strcmp performs a character to character 
comparison. 

Return Value strcol 1 returns an integer value indicating the relationship between the strings, as 
listed below: 

Value Meaning 

Less than 0 stringl is less than string2 

0 stringl is equivalent to string2 

Greater than 0 stringl is greater than string2 

Notes: 

1. strcoll might need to allocate additional memory to perform the comparison 
algorithm specified in the LC_COLLATE. If the memory request cannot be 
satisfied (by malloc), then strcoll fails. 

2. If the locale supports double-byte characters (MB_CUR_MAX specified as 2), 
strcoll validates the multibyte characters. (Previously, strcoll did not 
validate the string.) strcoll will fail if the string contains invalid multibyte 
characters. 

3. If MB_CUR_MAX is specified as 2, but the charmap file does not specify the 
DBCS characters, the DBCS characters will collate after the single-byte 
characters. 

This example compares the two strings passed to main. 
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#include <stdio.h> 

#include <string.h> 

int main(int argc.char **argv) 

{ 

int result; 



if (argc != 3) { 

printf("Usage: %s stringl string2\n", argv[G]); 

} 

else { 

result = strcoll(argv[l], argv[2]); 
if (0 == result) 

printf("\"%s\" is identical to \"%s\"\n", argv[l], argv[2]); 
else 

i f (result < 0) 

printf("\"%s\" is less than \"%s\"\n", argv[l], argv[2]); 
else 

printf("\"%s\" is greater than \"%s\"\n", argv[l], argv[2]); 

} 

return 0; 

/**************************************************************************** 
If the program is passed the following arguments: 

"firststring" "secondstring" 

The output should be: 

"firststring" is less than "secondstring" 
****************************************************************************/ 

} 

• “setlocale — Set Locale” on page 530 

• “strcmp — Compare Strings” on page 567 

• “strcmpi — Compare Strings Without Case Sensitivity” on page 569 

• “strncmp — Compare Strings” on page 597 

• “wcscoll —Compare Wide-Character Strings” on page 754 

• “<string.h>” on page 818 
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strcpy — Copy Strings 

Format linclude <string.h> 

char *strcpy(char *stringl, const char *string2 ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strcpy copies string2 , including the ending null character, to the location specified 
by stringl. 

strcpy operates on null-terminated strings. The string arguments to the function 
should contain a null character (\Q) marking the end of the string. No length 
checking is performed. You should not use a literal string for a stringl value, 
although string2 may be a literal string. 

Return Value strcpy returns a pointer to the copied string (stringl .). 

This example copies the contents of source to destination. 

#inc1ude <stdio.h> 

#inc1ude <string.h> 

Idefine SIZE 40 

int main(void) 

{ 

char source[SIZE] = "123456789"; 
char sourcel[SIZE] = "123456789"; 
char destination[SIZE] = "abcdefg"; 
char destinationl[SIZE] = "abcdefg"; 
char *return_string; 
int index = 5; 

/* This is how strcpy works */ 

printf("destination is originally = '%s'\n", destination); 
return_string = strcpy(destination, source); 

printf("After strcpy, destination becomes '%s'\n\n", destination); 
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/* This is how strncpy works */ 

printf("destinationl is originally = '%s'\n", destinationl); 
return_string = strncpy(destinationl, sourcel, index); 
printf("After strncpy, destinationl becomes '%s'\n", destinationl); 
return 0; 

/**************************************************************************** 

The output should be: 

destination is originally = 'abcdefg' 

After strcpy, destination becomes '123456789' 

destinationl is originally = 'abcdefg' 

After strncpy, destinationl becomes '12345fg' 
****************************************************************************/ 

} 



“strcat — Concatenate Strings” on page 565 

“strdup — Duplicate String” on page 578 

“strncpy — Copy Strings” on page 599 

“wcscpy — Copy Wide-Character Strings” on page 756 

“wcsncpy — Copy Wide-Character Strings” on page 768 

“<string.h>” on page 818 


574 VisualAge C++ C Library Reference 




strcspn 


strcspn — Compare Strings for Substrings 

Format linclude <string.h> 

size_t strcspn(const char *stringl, const char *string2); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strcspn finds the first occurrence of a character in stringl that belongs to the set of 
characters specified by string2. Ending null characters are not considered in the 
search. 

The strcspn function operates on null-terminated strings. The string arguments to the 
function should contain a null character (\0) marking the end of the string. 

Return Value strcspn returns the index of the first character found. This value is equivalent to 

the length of the initial substring of stringl that consists entirely of characters not 
in string2. 

This example uses strcspn to find the first occurrence of any of the characters a, x, 1 
or e in string. 

#inc1ude <stdio.h> 

#inc1ude <string.h> 

Idefine SIZE 40 

int main(void) 

{ 

char string[SIZE] = "This is the source string"; 
char *substring = "axle"; 

printf("The first %i characters in the string \"%s\" are not in the " 

"string \"%s\" \n", strcspn(string, substring), string, substring); 
return 0; 

/**************************************************************************** 

The output should be: 

The first 10 characters in the string "This is the source string" are not 
in the string "axle" 

****************************************************************************/ 

} 

• “strchr — Search for Character” on page 566 

• “strcmp — Compare Strings” on page 567 

• “strcmpi — Compare Strings Without Case Sensitivity” on page 569 

• “stri cmp — Compare Strings as Lowercase” on page 591 

• “strncmp — Compare Strings” on page 597 

• “strnicmp — Compare Strings Without Case Sensitivity” on page 601 

• “strpbrk — Find Characters in String” on page 604 
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• “strspn — Search Strings” on page 614 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcsncmp — Compare Wide-Character Strings” on page 766 

• “<string.h>” on page 818 
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strdate — Copy Current Date 

Format linclude <time.h> 

char *_strdate(char *date ); 


Description Language Level: Extension 

_strdate stores the current date as a string in the buffer pointed to by date in the 
following format: 

mm/dd/yy 

The two digits mm represent the month, the digits dd represent the day of the month, 
and the digits yy represent the year. For example, the string 10/08/91 represents 
October 8, 1991. The buffer must be at least 9 bytes. 

Note: The time and date functions begin at 00:00:00 Coordinated Universal Time, 
January 1, 1970. 


Return Value 


_strdate returns a pointer to the buffer containing the date string. There is no 
error return. 



This example prints the current date. 

#include <stdio.h> 

#include <time.h> 

int main(void) 

{ 

char buffer[9]; 


printf("The current date is %s \n", _strdate(buffer)); 
return 0; 


/**************************************************************************** 
The output should be similar to: 

The current date is 01/02/95 

****************************************************************************/ 

} 



“asctime — Convert Time to Character String” on page 55 

“ctime — Convert Time to Character String” on page 129 

“_ftime — Store Current Time” on page 285 

“gmtime — Convert Time” on page 321 

“1 ocal time — Convert Time” on page 385 

“mktime — Convert Local Time” on page 438 

“time — Determine Current Time” on page 666 

“tzset — Assign Values to Locale Information” on page 681 

“<time.h>” on page 819 
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strdup — Duplicate String 

Format linclude <string.h> 

char *strdup(const char ^string ); 

Description Language Level: XPG2, Extension 

strdup reserves storage space for a copy of string by calling mal loc. The string 
argument to this function is expected to contain a null character (\0) marking the end 
of the string. Remember to free the storage reserved with the call to strdup. 

Return Value strdup returns a pointer to the storage space containing the copied string. If it 
cannot reserve storage strdup returns NULL. 

This example uses strdup to duplicate a string and print the copy. 

linclude <stdio.h> 
linclude <string.h> 

int main(void) 

{ 

char *string = "this is a copy"; 
char *newstr; 

/* Make newstr point to a duplicate of string */ 

if ((newstr = strdup(string)) != NULL) 

printf("The new string is: %s\n", newstr); 
return 0; 

/•k-k-kle-k-kle-k-kle-k-k'k-k-klc-k-k'k-k-k'k'k-k'k-k-k'k-k-kle-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k 

The output should be: 

The new string is: this is a copy 

■k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-kle-k-k'k-k-k'k-k-kle-k-klc-k-kle-k-k'k-k-k-k-k-kle-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-kit-k-k'k/ 

) 

• “strcpy — Copy Strings” on page 573 

• “strncpy — Copy Strings” on page 599 

• “wcscpy — Copy Wide-Character Strings” on page 756 

• “wcsncpy — Copy Wide-Character Strings” on page 768 

• “<string.h>” on page 818 
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strerror — Set Pointer to Runtime Error Message 

Format linclude <string.h> 

char *strerror(int errnum ); 

Description Language Level: ANSI, SAA, XPG4 

strerror maps the error number in errnum to an error message string. 

Return Value strerror returns a pointer to the string. It does not use the program locale in any 
way. 

The value of errno may be set to: 

EILSEQ An encoding error has occurred converting a multibyte character. 

E2BIG The output buffer is too small. 

This example opens a file and prints a runtime error message if an error occurs. 

#include <stdio.h> 

#inc1ude <string.h> 

#inc1ude <errno.h> 

Idefine FILENAME "strerror.dat" 

int main(void) 

{ 

FILE *stream; 

if (NULL == (stream = fopen(FILENAME, "r"))) 
printf(" %s \n", strerror(errno)); 
return 0; 

} 

• “cl earerr — Reset Error Indicators.” on page 94 

• “terror — Test for Read/Write Errors” on page 223 

• “perror — Print Error Message” on page 459 

• “_strerror — Set Pointer to System Error String” on page 580 

• “<string.h>” on page 818 
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_strerror 

Format 

Description 


Return Value 


Set Pointer to System Error String 

linclude <string.h> 

char *_strerror(char *string ); 

Language Level: Extension 

_strerror tests for system error. It gets the system error message for the last library 
call that produced an error and prefaces it with your string message. 

Your string message can be a maximum of 94 bytes. 

Unlike perror, _strerror by itself does not print a message. To print the message 
returned by _strerror to stdout, use a printf statement similar to the following: 

if ((access("datafi1e",2)) == -1) 
printf(stderr,_strerror(NULL)); 

You could also print the message to stderr with an fprintf statement. 

To produce accurate results, call _strerror immediately after a library function 
returns with an error. Otherwise, subsequent calls might write over the errno value. 

If string is equal to NULL, _strerror returns a pointer to a string containing the 
system error message for the last library call that produced an error, ended by a 
new-line character (\n). 

If string is not equal to NULL, _strerror returns a pointer to a string containing: 

• Your string message 

• A colon 

• A space 

• The system error message for the last library call producing an error 

• A new-line character (\n). 
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This example shows how _strerror can be used with the fopen function. 

#include <string.h> 

#include <stdio.h> 

#define INFILE "_strerro.in" 

Idefine OUTFILE "_strerro.out" 

int main(void) 

{ 

FILE *fhl,*fh2; 

fhl = fopen(INFILE, "r"); 
if (NULL == fhl) 

/* the error message goes through stdout not stderr */ 

printf(_strerror("Open failed on input file")); 
fh2 = fopen(OUTFILE, "w+“); 
if (NULL == fh2) 

printf(_strerror("Open failed on output file")); 
el se 

printf("Open on output file was successful.\n"); 
if (fhl != NULL) 
fclose(fhl); 
if (fh2 != NULL) 
fclose(fh2); 
remove(OUTFILE); 
return 0; 

/**************************************************************************** 
The output should be: 

Open failed on input file: The file cannot be found. 

Open on output file was successful. 

****************************************************************************/ 


• “cl earerr — Reset Error Indicators.” on page 94 

• “ferror — Test for Read/Write Errors” on page 223 

• “perror — Print Error Message” on page 459 

• “strerror — Set Pointer to Runtime Error Message” on page 579 

• “<string.h>” on page 818 
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strfmon — Convert Monetary Value to String 

Format linclude <monetary.h> 

int strfmon(char *s, size_t maxsize, const char * format, ...); 

Description Language Level: XPG4 

strfmon places characters into the array pointed to by *s, as controlled by the string 
pointed to by format. No more than maxsize characters are placed into the array. 

The character string format contains two types of objects: 

• Plain characters, which are copied to the output array. 

• Directives, each of which results in the fetching of zero or more arguments that 
are converted and formatted. 

The results are undefined if there are insufficient arguments for the format. If the 
format is exhausted while arguments remain, the excess arguments are simply 
ignored. If objects pointed to by s and format overlap, the behavior is undefined. 

The directive (conversion specification) consists of the following sequence. 

1. A % character 

2. Optional flags, described below: =/, A then +, C, (, then ! 

3. Optional field width (may be preceded by -) 

4. Optional left precision: #n 

5. Optional right precision: .p 

6. Required conversion character to indicate what conversion should be performed: i 
or n. 

Each directive is replaced by the appropriate characters, as described in the following 
list: 

%i The double argument is formatted according to the locale's international 

currency format (for example, in USA: USD 1,234.56). 

%n The double argument is formatted according to the locale's national 

currency format (for example, in USA: $1,234.56). 

%% is replaced by %. No argument is converted. 

You can give optional conversion specifications immediately after the initial % of a 
directive in the following order: 
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Specifier 

=f 


+ I C I ( 


H v 

#n 


Meaning 

Specifies f as the numeric fill character. This flag is used in 
conjunction with the maximum digits specification #n (see below). 

The default numeric fill character is the space character. This option 
does not affect the other fill operations that always use a space as the 
fill character. 

Formats the currency amount without thousands grouping characters. 
The default is to insert the grouping characters if defined for the 
current locale. 

Specifies the style of representing positive and negative currency 
amounts. You can specify only one of +, C, or (. The + specifies to 
use the locale's equivalent of + and -. For example, in USA, the 
empty (null) string if positive and - if negative. C specifies to use the 
locale's equivalent of DB for negative and CR for positive. The ( 
specifies to use the locale's equivalent of enclosing negative amounts 
within parenthesis. If this option is not included, a default specified by 
the current locale is used. 

Suppresses the currency symbol from the output conversion. 

A decimal digit string that specifies a minimum field width in which 
the result of the conversion is right-justified (or left-justified if the - 
flag is specified). 

A decimal digit string that specifies a maximum number of digits 
expected to be formatted to the left of the radix character. You can 
use this option to keep the formatted output from multiple calls to 
strfmon aligned in the same columns. You can also use it to fill 
unused positions with a special character, as in $***123.45. This 
option causes an amount to be formatted as if it has the number of 
digits specified by n. If more digit positions are required than 
specified, this conversion specification is ignored. Digit positions in 
excess of those actually required are filled with the numeric fill 
character. (See the =/ specification above). 

If thousands grouping is enabled, the behavior is: 

1. Format the number as if it is an n digit number. 

2. Insert fill characters to the left of the leftmost digit (for example, 
$0001234.56 or $***1234.56). 

3. Insert the separator character (for example, $0,001,234.56 or 
$*,**1,234.56). 
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Return Value 



4. If the fill character is not the digit zero, the separators are replaced 
by the fill character (for example, $****1,234.56). 

To ensure alignment, any characters appearing before or after the 
number in the formatted output, such as currency or sign symbols, are 
padded with space characters to make their positive and negative 
formats an equal length. 

.p A decimal digit string that specifies the number of digits after the radix 

character. If the value of the precision p is 0, no radix character 
appears. If this option is not included, a default specified by the 
current locale is used. The amount being formatted is rounded to the 
specified number of digits prior to formatting. 

The LC_MONETARY category of the program's locale affects the behavior of this 
function, including the monetary radix character (which is different from the numeric 
radix character affected by the LC_NUMERIC category), the thousands (or alternate 
grouping) separator, the currency symbols, and formats. The international currency 
symbol should be in accordance with those specified in ISO 4217 Codes for the 
representation of currencies and funds. 

If the total number of resulting bytes including the terminating null character is not 
more than maxsize , strfmon returns the number of bytes placed into the array 
pointed to by s, not including the terminating null character. Otherwise, strfmon 
returns -1 and the contents of the array are indeterminate. 

This example uses strfmon to format the monetary value for money, then prints the 
resulting string. 

linclude <monetary.h> 

#include <1ocale.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

char string[100]; /* hold the string returned from strfmon() */ 

double money = 1234.56; 
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if (NULL == setlocale(LC_ALL, "en_us.ibm-850")) { 
printf("Unable to setlocale().\n"); 
exit(EXIT_FAILURE); 

} 

strfmon(string, 100, "%i", money); 

printf("International currency format = \"%s\"\n", string); 
strfmon(string, 100, "%n", money); 

printf("National currency format = \"%s\"\n", string); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

International currency format = "USD 1,234.56" 

National currency format = "$1,234.56" 
****************************************************************************/ 


“strftime — Convert to Formatted Time” on page 586 
“<monetary.h>” on page 812 


Chapter 3. Library Functions 585 



strftime 


strftime - 

Format 

Description 


Convert to Formatted Time 

linclude <time.h> 

size_t strftime(char *dest, size_t maxsize, 

const char *format, const struct tm *timeptr); 

Language Level: ANSI, SAA, XPG4, POSIX 

strftime converts the time and date specification in the timeptr structure into a 
character string. It then stores the null-terminated string in the array pointed to by 
dest according to the format string pointed to by format, maxsize specifies the 
maximum number of characters that can be copied into the array. 

The format string is a multibyte character string containing: 

• Conversion specification characters, preceded by a % sign. 

• Ordinary multibyte characters, which are copied into the array unchanged. 

If data has the form of a conversion specifier, but is not one of the accepted 
specifiers, the characters following the % are copied to the output. 

The characters that are converted are determined by the LC_CTYPE category of the 
current locale and by the values in the time structure pointed to by timeptr. The 
time structure pointed to by timeptr is usually obtained by calling the gmtime or 
local time function. 

When objects to be copied overlap, the behavior is undefined. 

strftime obtains time zone information from an internal structure. You can set the 
values in this structure by calling either tzset or setlocale. tzset sets the 
structure according to the information in the TZ environment variable; setlocale 
sets it according to the LC_TOD category in the current locale. If you do not set the 
values by calling one of these functions, the defaults used are EST for time zone 
name, EDT for Daylight Savings time zone name, and 300 minutes for time zone. 


The following table lists the strftime conversion specifiers: 


Table 5 (Page 1 of 4). Conversion Specifiers Used by strftime 

Specifier 

Meaning 

%a 

Replace with abbreviated weekday name of locale. 

%A 

Replace with full weekday name of locale. 

%b 

Replace with abbreviated month name of locale. 

%B 

Replace with full month name of locale. 
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Table 5 (Page 2 of 4). Conversion Specifiers Used by strftime 

Specifier 

Meaning 

%c 

Replace with date and time of locale. 

%C 

Replace with locale's century number (year divided by 100 and truncated) 

%d 

Replace with day of the month (01-31). 

%D 

Insert date in mm/dd/yy form, regardless of locale. 

%e 

Insert month of the year as a decimal number (01-12). 

Under POSIX, it's a 2-character, right-justified, blank-filled field. 

%E[cCxXyY] 

If the alternate date/time format is not available, the %E descriptors are 
mapped to their unextended counterparts. For example, %EC is mapped to 
%C. 

%Ec 

Replace with the locale's alternative date and time representation. 

%EC 

Replace with the name of the base year (period) in the locale's alternate 
representation. 

%Ex 

Replace with the locale's alternative date representation. 

%EX 

Replace with the locale's alternative time representation. 

%Ey 

Replace with the offset from %EC (year only) in the locale's alternate 
representation. 

%EY 

Replace with the full alternative year representation. 

%h 

Replace with locale's abbreviated month name. This is the same as %b. 

%H 

Replace with hour (24-hour clock) as a decimal number (00-23). 

%I 

Replace with hour (12-hour clock) as a decimal number (01-12). 

%j 

Replace with day of the year (001-366). 

%m 

Replace with month (01-12). 

%M 

Replace with minute (00-59). 

%n 

Replace with a new line. 


%0[deHImMSUwWy] 


If the alternative date/time format is not available, the %0 descriptors are 
mapped to their unextended counterparts. For example, %Od is mapped to 
%d. 


%Od 

Replace with the day of month, using the locale's alternative numeric 
symbols, filled as needed with leading zeroes if there is any alternative 
symbol for zero; otherwise fill with leading spaces. 

%Oe 

Replace with the day of the month, using the locale's alternative numeric 
symbols, filled as needed with leading spaces. 
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Table 5 (Page 3 of 4). Conversion Specifiers Used by strftime 

Specifier 

Meaning 

%OH 

Replace with the hour (24-hour clock), using the locale's alternative numeric 
symbols. 

%OI 

Replace with the hour (12-hour clock), using the locale's alternative numeric 
symbols. 

%0m 

Replace with the month, using the locale's alternative numeric symbols. 

%OM 

Replace with the minutes, using the locale's alternative numeric symbols. 

%OS 

Replace with the seconds, using the locale's alternative numeric symbols. 

%Ou 

Replace with the weekday as a decimal number (1 to 7), with 1 representing 
Monday, using the locale's alternative numeric symbols. 

%OU 

Replace with the week number of the year (00-53), where Sunday is the first 
day of the week, using the locale's alternative numeric symbols. 

&0V 

Replace with week number of the year (01-53), where Monday is the first day 
of the week, using the locale's alternative numeric symbols. 

%Ow 

Replace with the weekday (Sunday=0), using the locale's alternative numeric 
symbols. 

%OW 

Replace with the week number of the year (01-53), where Monday is the first 
day of the week, using the locale's alternative numeric symbols. 

%Oy 

Replace with the year (offset from %C) in the locale's alternative 
representation, using the locale's alternative numeric symbols. 

%p 

Replace with the locale's equivalent of AM or PM. 

%r 

Replace with a string equivalent to %I:%M:%S %p; or use t_fmt_ampm from 
LC_TIME, if present. 

%R 

Replace with time in 24 hour notation (%H:%M) 

%S 

Replace with second (00-61). 

%t 

Replace with a tab. 

%T 

Replace with a string equivalent to %H:%M:%S. 

%u 

Replace with the weekday as a decimal number (1 to 7), with 1 representing 
Monday. 

%U 

Replace with week number of the year (00-53), where Sunday is the first day 
of the week. 

%V 

Replace with week number of the year (01-53), where Monday is the first day 
of the week. 

%w 

Replace with weekday (0-6), where Sunday is 0. 
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Return Value 



Table 5 (Page 4 of 4). Conversion Specifiers Used by strftime 

Specifier 

Meaning 

%W 

Replace with week number of the year (00-53), where Monday is the first day 
of the week. 

%x 

Replace with date representation of locale. 

%X 

Replace with time representation of locale. 

%y 

Replace with year without the century (00-99). 

%Y 

Replace with year including the century. 

%Z 

Replace with name of time zone, or no characters if time zone is not 
available. 

%% 

Replace with %. 


For %Z, the tm_isdst flag in the tm structure passed to strftime specifies whether 
the time zone is standard or Daylight Savings time. 

If data has the form of a directive, but is not one of the above, the characters 
following the % are copied to the output. 


If the total number of characters in the resulting string, including the terminating 
null character, does not exceed maxsize , strftime returns the number of characters 
(bytes) placed into dest , not including the terminating null character. Otherwise, 
strftime returns 0 and the content of the string is indeterminate. 

This example gets the time and date from local time, calls strftime to format it, 
and prints the resulting string. 

#inc1ude <stdio.h> 

#include <time.h> 

int main(void) 

1 

char dest[70]; 
int ch; 
time_t temp; 
struct tm *timeptr; 
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temp = time(NULL); 
timeptr = localtime(&temp); 

ch = strftime(dest, sizeof(dest)-l, "Today is %A,"" %b %d. \n Time: %I:%M %p" 
, timeptr); 

printf("%d characters placed in string to make: \n \n %s", ch, dest); 
return 0; 

/**************************************************************************** 
The output should be similar to: 

41 characters placed in string to make: 

Today is Monday, Sep 16. 

Time: 06:31 pm 

****************************************************************************/ 

} 



“asctime — Convert Time to Character String” on page 55 
“ctime — Convert Time to Character String” on page 129 
“gmtime — Convert Time” on page 321 
“localtime — Convert Time” on page 385 
“setlocale — Set Locale” on page 530 

“strptime — Convert to Formatted Date and Time” on page 605 
“t i me — Determine Current Time” on page 666 
“wcsftime — Convert to Formatted Date and Time” on page 760 
“<time.h>” on page 819 
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stricmp — Compare Strings as Lowercase 

Format linclude <string.h> 

int stricmp(const char *stringl, const char *string2 ); 

Description Language Level: Extension 

stricmp compares stringl and string2 without sensitivity for case. All alphabetic 
characters in the arguments stringl and string2 are converted to lowercase before 
the comparison, stricmp operates on null-terminated strings. 

Return Value stricmp returns a value that indicates the following relationship between the two 
strings : 

Value Meaning 

Less than 0 stringl less than string2 

0 stringl identical to string2 

Greater than 0 stringl greater than string2. 

This example uses stricmp to compare two strings. 

#inc1ude <stdio.h> 

#inc1ude <string.h> 

int main(void) 

{ 

char *strl = "this is a string"; 
char *str2 = "THIS IS A STRING"; 

/* Compare two strings without regard to case */ 

if (stricmp(strl, str2)) 

printf("strl is not the same as str2\n"); 
el se 

printf("strl is the same as str2\n"); 
return 0; 

/**************************************************************************** 

The output should be: 

strl is the same as str2 

****************************************************************************/ 

i 

• “strcmp — Compare Strings” on page 567 

• “strcmpi — Compare Strings Without Case Sensitivity” on page 569 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strncmp — Compare Strings” on page 597 

• “strnicmp — Compare Strings Without Case Sensitivity” on page 601 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcsncmp — Compare Wide-Character Strings” on page 766 
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• “<string.h>” on page 818 
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strlen — Determine String Length 

Format linclude <string.h> 

size_t strlen(const char *string ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strlen determines the length of string excluding the terminating null character. 


Return Value strlen returns the length of string. 



This example determines the length of the string that is passed to main. 

#include <stdio.h> 
line!ude <string.h> 

int main(int argc.char **argv) 

{ 

char *String = "How long is this string?"; 


printf("Length of string \"%s\" is %i.\n". String, strlen(String)); 
return 0; 


/**************************************************************************** 
The output should be: 

Length of string "How long is this string?" is 24. 
****************************************************************************/ 

} 



“mbl en — Determine Length of Multibyte Character” on page 411 
“strrev — Reverse String” on page 612 

“wcslen — Calculate Length of Wide-Character String” on page 763 
“<string.h>” on page 818 
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strlwr — Convert Uppercase to Lowercase 

Format #include <string.h> 

char *strlwr(char *string); 

Description Language Level: Extension 

strlwr converts any uppercase letters in the given null-terminated string to 
lowercase. Other characters are not affected. 


Return Value strlwr returns a pointer to the converted string. There is no error return. 



This example makes a copy in all lowercase of the string "General Assembly", and 
then prints the copy. 

#include <string.h> 

#include <stdio.h> 


int main(void) 

{ 

char *string = "General Assembly"; 
char *copy; 

copy = strlwr(strdup(string)); 
printf("Expected result: general assembly\n"); 
printf("strlwr returned: %s\n", copy); 
return 0; 

/**************************************************************************** 

The output should be: 

Expected result: general assembly 
strlwr returned: general assembly 

****************************************************************************/ 



“strupr — Convert Lowercase to Uppercase” on page 631 
“_toascii - _tolower - _toupper — Convert Character” on page 673 
“tolower - toupper — Convert Character Case” on page 676 
“towlower - towupper — Convert Wide Character Case” on page 677 
“<string.h>” on page 818 
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strncat — Concatenate Strings 

Format linclude <string.h> 

char *strncat(char *stringl, const char *string2, size_t count); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strncat appends the first count characters of string2 to stringl and ends the 
resulting string with a null character (\0). If count is greater than the length of 
string2 , the length of string2 is used in place of count. 

The strncat function operates on null-terminated strings. The string argument to the 
function should contain a null character (\0) marking the end of the string. 


Return Value strncat returns a pointer to the joined string (stringl). 



This example demonstrates the difference between strcat and strncat. strcat 
appends the entire second string to the first, whereas strncat appends only the 
specified number of characters in the second string to the first. 

#include <stdio.h> 

#include <string.h> 


Idefine SIZE 40 


int main(void) 

{ 

char bufferl[SIZE] = "computer"; 
char *ptr; 

/* Call strcat with bufferl and " program" */ 

ptr = strcat(bufferl, " program"); 

printf("strcat : bufferl = \"%s\"\n", bufferl); 

/* Reset bufferl to contain just the string "computer" again */ 

memset(bufferl, 1 \0 1 , sizeof(bufferl)); 
ptr = strcpy(bufferl, "computer"); 

/* Call strncat with bufferl and " program" */ 

ptr = strncat(bufferl, " program", 3); 
printf("strncat: bufferl = \"%s\"\n", bufferl); 
return 0; 

/**************************************************************************** 
The output should be: 

strcat : bufferl = "computer program" 
strncat: bufferl = "computer pr" 

****************************************************************************/ 
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“strcat — Concatenate Strings” on page 565 

“strni cmp — Compare Strings Without Case Sensitivity” on page 601 
“wcscat — Concatenate Wide-Character Strings” on page 749 
“wcsncat — Concatenate Wide-Character Strings” on page 764 
“<string.h>” on page 818 
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strncmp — Compare Strings 

Format linclude <string.h> 

int strncmp(const char *stringl , const char *string2, size_t count); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strncmp compares the first count characters of stringl and string2. 


Return Value strncmp returns a value indicating the relationship between the substrings, as 
follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

substringl less than substring2 
substringl equivalent to substring2 
substringl greater than substring2 



This example demonstrates the difference between strcmp and strncmp. 

#include <stdio.h> 

#include <string.h> 


Idefine SIZE 10 


int main(void) 

{ 

int result; 
int index = 3; 

char bufferl[SIZE] = "abcdefg"; 

char buffer2[SIZE] = "abcfg"; 

void print_result(int, char *, char *); 

result = strcmp(bufferl, buffer2); 
printf(“Comparison of each character\n"); 
printf(" strcmp: "); 
print_result(result, bufferl, buffer2); 
result = strncmp(bufferl, buffer2, index); 

printf("\nComparison of only the first %i characters\n", index); 

printf(" strncmp: "); 

print_result(result, bufferl, buffer2); 

return 0; 
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/**************************************************************************** 

The output should be: 

Comparison of each character 
strcmp: "abcdefg" is less than "abcfg" 

Comparison of only the first 3 characters 
strncmp: "abcdefg" is identical to "abcfg" 

****************************************************************************/ 

} 


void print_result(int res,char *p_bufferl,char *p_buffer2) 

{ 

if (0 == res) 

printf("\"%s\" is identical to \"%s\"\n", p_bufferl, p_buffer2); 
else 

if (res < 0) 

printf("\"%s\" is less than \"%s\"\n", p_bufferl, p_buffer2); 
el se 

printf("\"%s\" is greater than \"%s\"\n", p_bufferl, p_buffer2); 



“strcmp — Compare Strings” on page 567 

“strcmpi — Compare Strings Without Case Sensitivity” on page 569 
“strcol 1 — Compare Strings Using Collation Rules” on page 571 
“strcspn — Compare Strings for Substrings” on page 575 
“stri cmp — Compare Strings as Lowercase” on page 591 
“strni cmp — Compare Strings Without Case Sensitivity” on page 601 
“wcscmp — Compare Wide-Character Strings” on page 752 
“wcsncmp — Compare Wide-Character Strings” on page 766 
“<string.h>” on page 818 
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strncpy — Copy Strings 

Format linclude <string.h> 

char *strncpy(char *stringl, const char *string2, size_t count); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strncpy copies count characters of string2 to stringl. If count is less than or 
equal to the length of string2, a null character (\0) is not appended to the copied 
string. If count is greater than the length of string2. the stringl result is padded 
with null characters (\0) up to length count. 

Return Value strncpy returns a pointer to stringl. 

This example demonstrates the difference between strcpy and strncpy. 

#inc1ude <stdio.h> 

#inc1ude <string.h> 

Idefine SIZE 40 

int main(void) 

{ 

char source[SIZE] = "123456789"; 
char sourcel[SIZE] = "123456789"; 
char destination[SIZE] = "abcdefg"; 
char destinationl[SIZE] = "abcdefg"; 
char *return_string; 
int index = 5; 

/* This is how strcpy works */ 

printf("destination is originally = 1 %s'\n", destination); 
return_string = strcpy(destination, source); 

printf("After strcpy, destination becomes '%s'\n\n", destination); 

/* This is how strncpy works */ 

printf("destinationl is originally = 1 %s 1 \n", destination!); 
return_string = strncpy(destinationl, sourcel, index); 
printf("After strncpy, destinationl becomes '%s'\n", destinationl); 
return 0; 
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/**************************************************************************** 

The output should be: 

destination is originally = 'abcdefg' 

After strcpy, destination becomes '123456789' 

destinationl is originally = 'abcdefg' 

After strncpy, destinationl becomes '12345fg' 
****************************************************************************/ 

} 



“strcpy — Copy Strings” on page 573 
“strdup — Duplicate String” on page 578 

“strni cmp — Compare Strings Without Case Sensitivity” on page 601 
“<string.h>” on page 818 
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strnicmp — Compare Strings Without Case Sensitivity 

Format linclude <string.h> 

int strnicmp (const char *stringl, const char *string2, int n ); 


Description Language Level: Extension 

strnicmp compares, at most, the first n characters of stringl and string2. It 
operates on null-terminated strings. 

strnicmp is case insensitive; the uppercase and lowercase forms of a letter are 
considered equivalent. 


Return Value strnicmp returns a value indicating the relationship between the substrings, as listed 
below: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

substringl less than substring2 
substringl equivalent to substring2 
substringl greater than substring2. 



This example uses strnicmp to compare two strings. 

#include <string.h> 

#include <stdio.h> 

int main(void) 

{ 

char *strl = "THIS IS THE FIRST STRING"; 
char *str2 = "This is the second string"; 
int numresult; 


/* Compare the first 11 characters of strl and str2 

without regard to case */ 

numresult = strnicmp(strl, str2, 11); 
if (numresult < 0) 

printf("String 1 is less than string2.\n"); 
el se 

if (numresult > 0) 

printf("String 1 is greater than string2.\n"); 
el se 

printf("The two strings are equivalent.\n"); 
return 0; 

/**************************************************************************** 
The output should be: 

The two strings are equivalent. 

****************************************************************************/ 

} 



“strcmp — Compare Strings” on page 567 
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• “strcmpi — Compare Strings Without Case Sensitivity” on page 569 

• “stri cmp — Compare Strings as Lowercase” on page 591 

• “strncmp — Compare Strings” on page 597 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcsncmp — Compare Wide-Character Strings” on page 766 

• “<string.h>” on page 818 
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strnset - strset — Set Characters in String 

Format linclude <string.h> 

char *strnset(char *string, int c, size_t n); 
char *strset(char * string , int c); 

Description Language Level: Extension 

strnset sets, at most, the first n characters of string to c (converted to a char). If 
n is greater than the length of string , the length of string is used in place of n. 
strset sets all characters of string , except the ending null character (\0), to c 
(converted to a char). 

For both functions, the string must be initialized and must end with a null character 

(\ 0 ). 

Return Value Both strset and strnset return a pointer to the altered string. There is no error 
return value. 

In this example, strnset sets not more than four characters of a string to the 
character 'x'. Then the strset function changes any non-null characters of the 
string to the character 1 k'. 

#inc1ude <stdio.h> 

#include <string.h> 

int main(void) 

{ 

char *str = "abcdefghi"; 
printf("This is the string: %s\n", str); 

printf("This is the string after strnset: %s\n", strnset(str, 'x', 4)); 
printf("This is the string after strset: %s\n", strset(str, 'k')); 
return 0; 

/**************************************************************************** 

The output should be: 

This is the string: abcdefghi 
This is the string after strnset: xxxxefghi 
This is the string after strset: kkkkkkkkk 
****************************************************************************/ 

} 

• “strchr — Search for Character” on page 566 

• “strpbrk — Find Characters in String” on page 604 

• “wcschr — Search for Wide Character” on page 750 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “<string.h>” on page 818 
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strpbrk — Find Characters in String 

Format linclude <string.h> 

char *strpbrk(const char *stringl, const char *string2 ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strpbrk locates the first occurrence in the string pointed to by stringl of any 
character from the string pointed to by string2. 

Return Value strpbrk returns a pointer to the character. If stringl and string2 have no 
characters in common, a NULL pointer is returned. 

This example returns a pointer to the first occurrence in the array string of either a 
or b. 

linclude <stdio.h> 
linclude <string.h> 

int main(void) 

{ 

char *result,*string = "A Blue Danube"; 
char *chars = "ab"; 

result = strpbrk(string, chars); 

printf("The first occurrence of any of the characters \“%s\" in " 

"\"%s\" is \"%s\"\n", chars, string, result); 
return 0; 

/**************************************************************************** 

The output should be: 

The first occurrence of any of the characters "ab" in 
"A Blue Danube" is "anube" 

****************************************************************************/ 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “wcsrchr — Locate Wide Character in String” on page 772 

• “wcswcs — Locate Wide-Character Substring” on page 788 

• “<string.h>” on page 818 




604 VisualAge C++ C Library Reference 




strptime 


strptime — Convert to Formatted Date and Time 

Format linclude <time.h> 

char *strptime(const char *buf, const char *fmt, struct tm *tm ); 

Description Language Level: XPG4 

strptime uses the format specified by fmt to convert the character string pointed to 
by buf to values that are stored in the structure pointed to by tm. 

The *fmt is composed of zero or more directives. Each directive is composed of one 
of the following: 

• One or more white-space characters (as specified by the i sspace function) 

• An ordinary character (neither % nor a white-space character) 

• A conversion specifier. 

Each conversion specifier consists of a % character followed by a conversion 
character that specifies the replacement required. There must be white-space or other 
non-alphanumeric characters between any two conversion specifiers. 

For a directive composed of white-space characters, strptime scans input up to the 
first character that is not white space (which remains unscanned), or until no more 
characters can be scanned. 

For a directive that is an ordinary character, strptime scans the next character from 
the buffer. If the scanned character differs from the one comprising the directive, the 
directive fails and the differing and subsequent characters remain unscanned. 

For a series of directives composed of %n, %t, white-space characters, or any 
combination, strptime scans up to the first character that is not white space (which 
remains unscanned), or until no more characters can be scanned. 

For any other conversion specification, strptime scans characters until a character 
matching the next directive is scanned, or until no more characters can be scanned. It 
then compares these characters, excepting the one matching the next directive, to the 
locale values associated with the conversion specifier. If a match is found, strptime 
sets the appropriate tm structure members to values corresponding to the locale 
information. Case is ignored when items in buf are matched, such as month or 
weekday names. If no match is found, strptime fails and no more characters are 
scanned. 
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The following tables list the conversion specifiers for strptime. 


Table 6 (Page 1 of 2). Conversion Specifiers Used by strptime 

Specifier 

Meaning 

%a 

Day of week, using locale's abbreviated or full weekday name. 

%A 

Day of week, using locale's abbreviated or full weekday name. 

%b 

Month, using locale's abbreviated or full month name. 

%B 

Month, using locale's abbreviated or full month name. 

%c 

Date and time, using locale's date and time. 

%C 

Century number (year divided by 100 and truncated to an integer) 

%d 

Day of the month (1-31; leading zeros permitted but not required). 

%D 

Date as %m/%d/%y. 

%e 

Day of the month (1-31; leading zeros permitted but not required). 

%h 

Month, using locale's abbreviated or full month name. 

%H 

Hour (0-23; leading zeros permitted but not required). 

%l 

Hour (0-12; leading zeros permitted but not required). 

%} 

Day number of the year (001-366). 

%m 

Month number (1-12; leading zeros permitted but not required). 

%M 

Minute (0-59; leading zeros permitted but not required). 

%n 

Newline character. 

%p 

Locale's equivalent of AM or PM. 

%r 

Time as %I:%M:%S a.m. or %I:%M:%S p.m. 

%R 

Time in 24 hour notation (%H%M) 

%S 

Seconds (0-61; leading zeros permitted but not required). 

%t 

Tab character. 

%T 

Time as %H:%M:%S. 

%U 

Week number of the year (0-53; where Sunday is the first day of the week; 
leading zeros permitted but not required). 

%w 

Weekday (0-6; where Sunday is 0; leading zeros permitted but not required). 

%W 

Week number of the year (0-53; where Monday is the first day of the week; 
leading zeros permitted but not required). 

%x 

Date, using locale's date format. 

%X 

Time, using locale's time format. 
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Table 6 (Page 2 of 2). Conversion Specifiers Used by strptime 

Specifier 

Meaning 

%y 

Year within century (0-99; leading zeros permitted but not required). 

%Y 

Year, including century. 

%Z 

Time zone name 

%% 

Replace with %. 


Some directives can be modified by the E or O modifier characters to indicate that an 
alternative format or specification should be used rather than the one normally used 
by the unmodified directive. If the alternative format or specification does not exist 
in the current locale, the behavior will be as if the unmodified directive were used. 


Table 7 (Page 1 of 2). Modified Directives Used by strptime 

Specifier 

Meaning 

%Ec 

Replace with the locale's alternative date and time representation. 

%EC 

Replace with the name of the base year (period) in the locale's alternative 
representation. 

%Ex 

Replace with the locale's alternative date representation. 

%EX 

Replace with the locale's alternative time representation. 

%Ey 

Replace with the offset from %EC (year only) in the locale's alternative 
representation. 

%EY 

Replace with the full alternative year representation. 

%Od 

Replace with the day of month, using the locale's alternative numeric 
symbols, filled as needed with leading zeroes if there is any alternative 
symbol for zero; otherwise, fill with leading spaces. 

%Oe 

Replace with the day of the month, using the locale's alternative numeric 
symbols, filled as needed with leading spaces. 

%OH 

Replace with the hour (24-hour clock), using the locale's alternative numeric 
symbols. 

%OI 

Replace with the hour (12-hour clock), using the locale's alternative numeric 
symbols. 

%Om 

Replace with the month, using the locale's alternative numeric symbols. 

%OM 

Replace with the minutes, using the locale's alternative numeric symbols. 

%os 

Replace with the seconds, using the locale's alternative numeric symbols. 
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Return Value 



Table 7 (Page 2 of 2). Modified Directives Used by strptime 

Specifier 

Meaning 

%OU 

Replace with the week number of the year (Sunday as the first day of the 
week, rules corresponding to %U), using the locale's alternative numeric 
symbols. 

%Ow 

Replace with the weekday (Sunday=0), using the locale's alternative numeric 
symbols. 

%OW 

Replace with the week number of the year (Monday as the first day of the 
week), using the locale's alternative numeric symbols. 

%Oy 

Replace with the year (offset from %C) in the locale's alternative 
representation, using the locale's alternative numeric symbols. 


If successful, strptime returns a pointer to the character following the last 
character parsed. Otherwise, a null pointer is returned. 

This example uses strptime to convert a string to the structure xmas, then prints the 
contents of the structure. 

#include <time.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

struct tm xmas; 

if (NULL == strptime("12/25/94 12:00:01", "%D %T\ &xmas)) { 
printf("strptime() failed.\n"); 
exit(EXIT_FAILURE); 

} 

printf("tm_sec = %3d\n", xmas.tm_sec ); 
printf("tm_min = %3d\n", xmas.tm_min ); 
printf("tm_hour = %3d\n", xmas.tm_hour); 
printf("tm_mday = %3d\n", xmas.tm_mday); 
printf("tm_mon = %3d\n", xmas.tm_mon ); 
printf("tm_year = %3d\n", xmas.tm_year); 
return 0; 

/•kic-kic-k-k'k-k-k'k-k-k-k-k'k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k'k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k 


The output 

should be similar to 

tm_sec = 

1 

tm min = 

0 

tm_hour = 

12 

tm mday = 

25 

tm mon = 

11 

tm_year = 

94 


■k , k-k-k-k-k-k‘k-k-k‘k-k-k‘k-ki<‘k'k-ki(-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k‘k-k-k‘k-k-kick-k‘k-k-k‘k-k-k‘k-k-k^ 

} 
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• “strftime — Convert to Formatted Time” on page 586 

• “wcsftime — Convert to Formatted Date and Time” on page 760 

• “<time.h>” on page 819 
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strrchr — Find Last Occurrence of Character in String 

Format linclude <string.h> 

char *strrchr(const char *string, int c); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strrchr finds the last occurrence of c (converted to a character) in string. The 
ending null character is considered part of the string. 

Return Value strrchr returns a pointer to the last occurrence of c in string. If the given 
character is not found, a NULL pointer is returned. 

This example compares the use of strchr and strrchr. It searches the string for the 
first and last occurrence of p in the string. 

linclude <stdio.h> 
linclude <string.h> 

Idefine SIZE 40 

int main(void) 

{ 

char buf [SIZE] = "computer program"; 
char *ptr; 
int ch = 1 p 1 ; 

/* This illustrates strchr */ 

ptr = strchr(buf, ch); 

printf("The first occurrence of %c in '%s 1 is '%s 1 \n", ch, buf, ptr); 

/* This illustrates strrchr */ 

ptr = strrchr(buf, ch); 

printf("The last occurrence of %c in '%s' is '%s'\n", ch, buf, ptr); 
return 0; 

/**************************************************************************** 

The output should be: 

The first occurrence of p in 'computer program 1 is 'puter program' 

The last occurrence of p in 'computer program' is 'program' 
****************************************************************************/ 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcspbrk — Locate Wide Characters in String” on page 770 
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“wcsrchr — Locate Wide Character in String” on page 772 
“wcswcs — Locate Wide-Character Substring” on page 788 
“<string.h>” on page 818 
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strrev — Reverse String 

Format linclude <string.h> 

char *strrev(char *string); 

Description Language Level: Extension 

strrev reverses the order of the characters in the given string. The ending null 
character (\0) remains in place. 

Return Value strrev returns a pointer to the altered string. There is no error return value. 

This example determines whether a string is a palindrome. A palindrome is a string 
that reads the same forward and backward. 

linclude <stdio.h> 
linclude <stdlib.h> 
linclude <string.h> 

int palindrome(char *string) 

{ 

char *string2; 

/* Duplicate string for comparison */ 

if (NULL == (string2 = strdup(string))) { 

printf("Storage could not be reserved for string\n"); 
exit(EXITFAILURE); 

} 

/* If result equals 0, the string is a palindrome */ 

return (strcmp(string, strrev(string2))); 

} 

int main(void) 

{ 

char string[81]; 

printf("Please enter a string.\n"); 
scant("%80s", string); 
if (palindrome(string)) 

printf("The string is not a palindrome.\n"); 
else 

printf("The string is a palindrome.\n"); 
return 0; 
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/**************************************************************************** 
Sample output from program: 

Please enter a string, 
level 

The string is a palindrome. 

... or ... 

Please enter a string, 
levels 

The string is not a palindrome. 

****************************************************************************/ 


• “strcat — Concatenate Strings” on page 565 

• “strcmp — Compare Strings” on page 567 

• “strcpy — Copy Strings” on page 573 

• “strdup — Duplicate String” on page 578 

• “strnset - strset — Set Characters in String” on page 603 

• “<string.h>” on page 818 
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strspn — Search Strings 

Format #include <string.h> 

size_t strspn(const char *stringl, const char *string2 ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strspn finds the first occurrence of a character in stringl that is not contained in the 
set of characters specified by string2. The null character (\0) that ends string2 is 
not considered in the matching process. 


Return Value strspn returns the index of the first character found. This value is equal to the 
length of the initial substring of stringl that consists entirely of characters from 
string2. If stringl begins with a character not in string2 , strspn returns 0. If all 
the characters in stringl are found in string2 , the length of stringl is returned. 



This example finds the first occurrence in the array string of a character that is not 
an a, b, or c. Because the string in this example is cabbage, strspn returns 5, the 
length of the segment of cabbage before a character that is not an a, b, or c. 

#include <stdio.h> 

#include <string.h> 


int main(void) 

{ 

char *string = "cabbage"; 
char *source = "abc"; 
int index; 


index = strspn(string, "abc"); 

printf("The first %d characters of \"%s\" are found in \"%s\"\n", index, 
string, source); 
return 0; 


The output should be: 

The first 5 characters of "cabbage" are found in "abc" 

■klt-k-k-k-k-kie-k-k-k-k-k'k-k-k'k-k-klt-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-kick-klck-klck-k'k-k-kick-k'k-k-k'k-k-k/ 

} 



“strehr — Search for Character” on page 566 

“strespn — Compare Strings for Substrings” on page 575 

“strpbrk — Find Characters in String” on page 604 

“strrehr — Find Last Occurrence of Character in String” on page 610 

“wesehr — Search for Wide Character” on page 750 

“wesespn — Find Offset of First Wide-Character Match” on page 758 

“wespbrk — Locate Wide Characters in String” on page 770 

“wesrehr — Locate Wide Character in String” on page 772 

“wesspn — Search Wide-Character Strings” on page 776 
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wcswcs — Locate Wide-Character Substring” on page 788 
<string.h>” on page 818 
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strstr — Locate Substring 

Format linclude <string.h> 

char *strstr(const char *stringl, const char *string2 ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

strstr finds the first occurrence of string2 in stringl. The function ignores the 
null character (\0) that ends string2 in the matching process. 

Return Value strstr returns a pointer to the beginning of the first occurrence of string2 in 

stringl. If s tring2 does not appear in stringl. strstr returns NULL. If string2 
points to a string with zero length, strstr returns stringl. 

This example locates the string haystack in the string "needle in a haystack", 
linclude <string.h> 

int main(void) 

{ 

char *stringl = "needle in a haystack"; 
char *string2 = "haystack"; 
char *result; 

result = strstr(stringl, string2); 

/* Result = a pointer to "haystack" */ 

printf(“%s\n", result); 
return 0; 

/•k-k-k-k-k-k-k-k-k'k-k-kle-k-k-k-k-k-k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-kick-k-k-k 

The output should be: 
haystack 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘ki!-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<i(-k-k-k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-kick-k-k-k-k-k-k-k‘k-k-k^ 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “wcsrchr — Locate Wide Character in String” on page 772 

• “wcsspn — Search Wide-Character Strings” on page 776 

• “wcswcs — Locate Wide-Character Substring” on page 788 

• “<string.h>” on page 818 
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_strtime — 

Format 

Description 


Return Value 



Copy Time 

linclude <time.h> 

char *_strtime(char *time); 

Language Level: Extension 

_strtime copies the current time into the buffer that time points to. The format is: 

hh:mm:ss 

where 

hh represents the hour in 24-hour notation, 
mm represents the minutes past the hour, 

SS represents the number of seconds. 

For example, the string 18:23:44 represents 23 minutes and 44 seconds past 6 p.m. 
The buffer must be at least 9 bytes. 

Note: The time and date functions begin at 00:00:00 Coordinated Universal Time, 
January 1, 1970. 

_strtime returns a pointer to the buffer. There is no error return. 

This example prints the current time: 

#include <stdio.h> 

#include <time.h> 

int main(void) 

{ 

char buffer[9]; 

printf("The current time is %s \n", _strtime(buffer)); 
return 0; 

/**************************************************************************** 

The output should be similar to: 

The current time is 16:47:22 

****************************************************************************/ 

i 

• “asctime — Convert Time to Character String” on page 55 

• “ctime — Convert Time to Character String” on page 129 

• “gmtime — Convert Time” on page 321 

• “localtime — Convert Time” on page 385 

• “mktime — Convert Local Time” on page 438 

• “time — Determine Current Time” on page 666 

• “tzset — Assign Values to Locale Information” on page 681 
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• “<time.h>” on page 819 
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strtocol1 

Format 

Description 


Return Value 



Return Collating Element for String 

linclude <collate.h> 

col Tel_t strtocol1(char *string ); 

Language Level: Extension 

strtocoll determines the collating element (col lei _t) that represents string. 

For a string of one character, the collating element always exists, and is the wchar_t 
of that character. For a string with more than one character, a valid collating element 
exists if the LC_COLLATE category contains the definition of a sequence of characters 
that collate as one for the purpose of culture-sensitive string comparison. This 
many-characters-to-one-collating-element relationship is also called many-to-one 
mapping. 


strtocoll returns the collating element (col 1 el_t value) for string, strtocoll 
returns (collei_t)-1 in the following cases: 

• If many-to-one mapping is not defined in the LC_COLLATE category of the 
current locale. 

• If the string is not a valid collating element . 

• If the string has zero length. 

• If the wchar_t for the first character in the string is greater than the maximum 
wchar_t value for the characters in the charmap file for the current locale. (This 
error occurs when the current locale is "C" or where MB_CUR_MAX is 2, and 
strtocoll is passed a double-byte character, but only single-byte characters are 
defined in the charmap file for the locale.) 

This example uses strtocol 1 to get the start and end collating-elements for the 
col 1 range function. 

#include <stdio.h> 

#include <1ocale.h> 

#include <col1 ate.h> 

#include <wchar.h> 
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int main(int argc, char *argv[]) 

{ 

col 1 el_t s, e, *rp; 

int i; 

setlocale(LC_ALL, LC_C_FRANCE); 

if ((col 1 el_t)-1 == (s = strtocol1(argv[ 1]))) { 

printf(" 1 %s' collating element not defined\n", argv[l]); 
exit(l); 

} 

if ((collei_t)-1 == (e = strtocol1(argv[2]))) { 

printf("'%s' collating element not defined\n", argv[2]); 
exit(l); 

} 

if (-1 == (i = collrange(s, e, &rp))) { 

printf("Invalid range for '%s 1 to '%s'\n", argv[l], argv[2]); 
exit(l); 


for (; i >0; rp++, i--) { 
if (ismccol1 el(*rp)) 

printf("'%s 1 ", col 1tostr(*rp)); 
else if (iswprint(*rp)) 

printf(" 1 %1c' ", *rp); 
el se 

printf('"%x' ", *rp); 

} 

return 0; 

/**************************************************************************** 
Assuming you enter: A z 

The output should be: 


'A' 1 B' 
'S' 'T' 
1 e' 1 f ' 
'w' 'x' 


' D 1 
■V 
1 h 1 
1 z' 


1 E 1 
1 i' 


' G' 
' Y 1 
' k 1 


'I' 'J' 
'm' 'n 1 


1 K' 
'o' 


' L 1 ' M' 


' P' 'Q' 
' b' 1 c' 

' t' ' u' 





“ccl ass — Return Characters in Character Class” on page 82 
“col 1 equi v — Return List of Equivalent Collating Elements” on page 101 
“col 1 order — Return List of Collating Elements” on page 103 
“col 1 range — Calculate Range of Collating Elements” on page 105 
“col 1 tostr — Return String for Collating Element” on page 107 
“getmccol 1 — Get Next Collating Element from String” on page 306 
“getwmccol 1 — Get Next Collating Element from Wide String” on page 319 
“i smccol 1 el — Identify Multi-Character Collating Element” on page 358 
“maxcol 1 — Return Maximum Collating Element” on page 409 
“<collate.h>” on page 802 
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strtod — Convert Character String to Double 

Format linclude <stdlib.h> 

double strtod(const char *nptr, char **endptr ); 

Description Language Level: ANSI, SAA, XPG4 

strtod converts a character string to a double-precision value. The parameter nptr 
points to a sequence of characters that can be interpreted as a numerical value of the 
type double. This function stops reading the string at the first character that it cannot 
recognize as part of a number. This character can be the null character at the end of 
the string. 

The strtod function expects nptr to point to a string with the following form: 



The first character that does not fit this form stops the scan. 

Return Value strtod returns the value of the floating-point number, except when the 

representation causes an underflow or overflow. For an overflow, it returns 
-HUGE_VAL or +HUGE_VAL; for an underflow, it returns 0. 

In both cases, errno is set to ERANGE, depending on the base of the value. If the 
string pointed to by nptr does not have the expected form, no conversion is 
performed and the value of nptr is stored in the object pointed to by endptr , 
provided that endptr is not a NULL pointer. 

strtod does not fail if a character other than a digit follows an E or e read in as an 
exponent. For example, IGOelf will be converted to the floating-point value 100.0. 
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This example converts the strings to a double value. It prints out the converted value 
and the substring that stopped the conversion. 

#include <stdlib.h> 

#include <stdio.h> 


int main(void) 

{ 

char *string,*stopstring; 
double x; 


string = "3.1415926This stopped it"; 

x = strtod(string, &stopstring); 

printf("string = %s\n", string); 

printf(" strtod = %f\n", x); 

printf(" Stopped scan at %s\n\n", stopstring); 

string = "lOGergs"; 

x = strtod(string, &stopstring); 

printf("string = \"%s\"\n", string); 

printf(" strtod = %f\n", x); 

printf(" Stopped scan at \"%s\"\n\n", stopstring); 
return 0; 

/**************************************************************************** 

The output should be: 

string = 3.1415926This stopped it 
strtod = 3.141593 
Stopped scan at This stopped it 

string = "IGOergs" 
strtod = 100.000000 
Stopped scan at "ergs" 

****************************************************************************/ 

} 



“atof — Convert Character String to Float” on page 63 

“atoi — Convert Character String to Integer” on page 65 

“atol — Convert Character String to Long Integer” on page 67 

“_atold — Convert Character String to Long Double” on page 69 

“strtol — Convert Character String to Long Integer” on page 625 

“strtold — Convert String to Long Double” on page 627 

“strtoul — Convert String Segment to Unsigned Integer” on page 629 

“wcstod — Convert Wide-Character String to Double” on page 778 

“wcstol — Convert Wide-Character to Long Integer” on page 782 

“wcstoul — Convert Wide-Character String to Unsigned Long” on page 786 

“<stdlib.h>” on page 816 
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strtok — Tokenize String 

Format linclude <string.h> 

char *strtok(char *stringl, const char *string2 ); 


Description Language Level: ANSI, SAA SAA, POSIX, XPG4 

strtok reads stringl as a series of zero or more tokens, and string2 as the set of 
characters serving as delimiters of the tokens in stringl. The tokens in stringl can 
be separated by one or more of the delimiters from string2. The tokens in stringl 
can be located by a series of calls to strtok. 

In the first call to strtok for a given stringl , strtok searches for the first token in 
stringl , skipping over leading delimiters. A pointer to the first token is returned. 

To read the next token from stringl. call strtok with a NULL stringl argument. A 
NULL stringl argument causes strtok to search for the next token in the previous 
token string. Each delimiter is replaced by a null character. The set of delimiters can 
vary from call to call, so string2 can take any value. 


Return Value The first time strtok is called, it returns a pointer to the first token in stringl. In 

later calls with the same token string, strtok returns a pointer to the next token in the 
string. A NULL pointer is returned when there are no more tokens. All tokens are 
null-terminated. 



Using a loop, this example gathers tokens, separated by blanks or commas, from a 
string until no tokens are left. After processing the tokens (not shown), the example 
returns the pointers to the tokens a,string, of, and tokens. The next call to strtok 
returns NULL, and the loop ends. 
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#include <stdio.h> 

#include <string.h> 

int main(void) 

{ 

char *token,*string = "a string, of, ,tokens\0,after null terminator"; 

/* the string pointed to by string is broken up into the tokens 
"a string", " of", " ", and "tokens" ; the null terminator (\0) 
is encountered and execution stops after the token "tokens" */ 

token = strtok(string, 
do { 

printf("token: %s\n", token); 

} while (token = strtok(NULL, 
return 0; 

/**************************************************************************** 

The output should be: 

token: a string 
token: of 
token: 

token: tokens 

****************************************************************************/ 



“strcat — Concatenate Strings” on page 565 

“strchr — Search for Character” on page 566 

“strcmp — Compare Strings” on page 567 

“strcpy — Copy Strings” on page 573 

“strcspn — Compare Strings for Substrings” on page 575 

“strspn — Search Strings” on page 614 

“wcstok — Tokenize Wide-Character String” on page 780 

“<string.h>” on page 818 
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strtol — Convert Character String to Long Integer 

Format linclude <stdlib.h> 

long int strtol(const char *nptr, char **endptr, int base); 

Description Language Level: ANSI, SAA, XPG4 

strtol converts a character string to a long-integer value. The parameter nptr points 
to a sequence of characters that can be interpreted as a numerical value of type 1 ong 
int. This function stops reading the string at the first character that it cannot 
recognize as part of a number. This character can be the null character (\0) at the 
end of the string. The ending character can also be the first numeric character greater 
than or equal to the base. 

When you use the strtol function, nptr should point to a string with the following 
form: 



white-space-^ 

- 1 - 


O O CD 
X X 1 

1 1 1 

digits—^ 


If base is in the range of 2 through 36, it becomes the base of the number. If base 
is 0, the prefix determines the base (8, 16, or 10): the prefix 0 means base 8 (octal); 
the prefix Ox or OX means base 16 (hexadecimal); using any other digit without a 
prefix means decimal. 

Return Value strtol returns the value represented in the string, except when the representation 

causes an overflow. For an overflow, it returns L0NG_MAX or L0NG_MIN, according to 
the sign of the value and errno is set to ERANGE. If base is not a valid number, 
strtol sets errno to EDOM. 


errno is set to ERANGE for the exceptional cases, depending on the base of the value. 
If the string pointed to by nptr does not have the expected form, no conversion is 
performed and the value of nptr is stored in the object pointed to by endptr, 
provided that endptr is not a NULL pointer. 



This example converts the strings to a 1 ong value. It prints out the converted value 
and the substring that stopped the conversion. 
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#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *string,*stopstring; 

1ong 1; 
int bs; 

string = "10110134932"; 
printf("string = %s\n", string); 
for (bs = 2; bs <= 8; bs *= 2) { 

1 = strtol(string, &stopstring, bs); 

printf(" strtol = %ld (base %d)\n", 1, bs); 

printf(" Stopped scan at %s\n\n", stopstring); 

} 

return 0; 

/**************************************************************************** 

The output should be: 

string = 10110134932 
strtol = 45 (base 2) 

Stopped scan at 34932 

strtol = 4423 (base 4) 

Stopped scan at 4932 

strtol = 2134108 (base 8) 

Stopped scan at 932 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k , k'k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-ki(-k-k‘k-k-k‘k-k-k-k-k-k , k-k-k‘k-k-kick-k‘k-k-k^ 

) 



“atof — Convert Character String to Float” on page 63 

“atoi — Convert Character String to Integer” on page 65 

“atol — Convert Character String to Long Integer” on page 67 

“_atold — Convert Character String to Long Double” on page 69 

“_1 toa — Convert Long Integer to String” on page 395 

“strtod — Convert Character String to Double” on page 621 

“strtol d — Convert String to Long Double” on page 627 

“strtoul — Convert String Segment to Unsigned Integer” on page 629 

“wcstod — Convert Wide-Character String to Double” on page 778 

“wcstol — Convert Wide-Character to Long Integer” on page 782 

“wcstoul — Convert Wide-Character String to Unsigned Long” on page 786 

“<stdlib.h>” on page 816 
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strtold — 

Format 

Description 


Convert String to Long Double 

linclude <stdlib.h> 

long double strtold(const char *nptr, char **endptr ); 

Language Level: Extension 

strtol d converts a character string pointed to by nptr to a long double value. 
When it reads a character it does not recognize as part of a number, strtold stops 
conversion and endptr points to the remainder of nptr. This character may be the 
ending null character. 

The string pointed to by nptr must have the following format: 



The digits are one or more decimal digits. If no digits appear before the decimal 
point, at least one digit must follow the decimal point. An exponent expressed as a 
decimal integer can follow the digits. The exponent can be signed. 

The value of nptr can also be one of the strings infinity, inf, or nan. These strings 
are case insensitive, and can be preceded by a unary minus (-). They are converted 
to infinity and NaN values. See “Infinity and NaN Support” on page 33 for more 
information about using infinity and NaN values. 

If the string pointed to by nptr does not have the expected form, no conversion is 
performed and endptr points to the value of nptr. 

The strtold function ignores any white-space characters, as defined by the isspace 
function. 
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Return Value If successful, strtol d returns the value of the long double number. If it fails, 
strtol d returns 0. For an underflow or overflow, it returns the following: 

Condition Return Value 

Underflow 0 with errno set to ERANGE 

Positive overflow +_LHUGE_VAL 

Negative overflow -_LHUGE_VAL. 

This example uses strtold to convert two strings, " -001234.5678el0end of 

string" and "NaNQthis cannot be converted" to their corresponding long double 
values. It also prints out the part of the string that cannot be converted. 

linclude <stdlib.h> 
linclude <stdio.h> 

int main(void) 

{ 

char *nptr; 
char *endptr; 

nptr = " -001234.5678el0end of string"; 

printf("strtold = %.10Le\n", strtold(nptr, &endptr)); 
printf("end pointer at = %s\n\n", endptr); 
nptr = "NaNthis cannot be converted"; 
printf("strtold = %.10Le\n", strtold(nptr, &endptr)); 
printf("end pointer at = %s\n\n", endptr); 
return 0; 

/**************************************************************************** 

The output should be: 

strtold = -1.2345678000e+13 
end pointer at = end of string 

strtold = nan 

end pointer at = this cannot be converted 

****************************************************************************/ 

} 

• “atof — Convert Character String to Float” on page 63 

• “atoi — Convert Character String to Integer” on page 65 

• “atol — Convert Character String to Long Integer” on page 67 

• “_atold — Convert Character String to Long Double” on page 69 

• “strtod — Convert Character String to Double” on page 621 

• “strtol — Convert Character String to Long Integer” on page 625 

• “strtoul — Convert String Segment to Unsigned Integer” on page 629 

• “wcstod — Convert Wide-Character String to Double” on page 778 

• “wcstol — Convert Wide-Character to Long Integer” on page 782 

• “wcstoul — Convert Wide-Character String to Unsigned Long” on page 786 

• “Infinity and NaN Support” on page 33 

• “<stdlib.h>” on page 816 
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strtoul — Convert String Segment to Unsigned Integer 

Format linclude <stdlib.h> 

unsigned long int strtoul(const char *stringl, char **string2, int base); 

Description Language Level: ANSI, SAA, XPG4 

strtoul converts a character string to an unsigned long integer value. The input 
stringl is a sequence of characters that can be interpreted as a numerical value of 
the type unsigned long int. strtoul stops reading the string at the first character 
that it cannot recognize as part of a number. This character can be the first numeric 
character greater than or equal to the base, strtoul sets string2 to point to the 
resulting output string if a conversion is performed, and provided that string2 is not 
a NULL pointer. 

When you use strtoul, stringl should point to a string with the following form: 



white-space-^ 

- 1 - 

__ 


o o o 
X X I 

1 1 1 

digits—^ 


If base is in the range of 2 through 36, it becomes the base of the number. If base 
is 0, the prefix determines the base (8, 16, or 10): the prefix 0 means base 8 (octal); 
the prefix Ox or OX means base 16 (hexadecimal); using any other digit without a 
prefix means decimal. 

Return Value strtoul returns the value represented in the string, or 0 if no conversion could be 

performed. For an overflow, strtoul returns UL0NG_MAX and sets errno to ERANGE. If 
base is not a valid number, strtoul sets errno to EDOM. 
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This example converts the string to an unsigned long value. It prints out the 
converted value and the substring that stopped the conversion. 

#include <stdio.h> 

#include <stdlib.h> 


#define BASE 2 

int main(void) 

{ 

char *string,*stopstring; 
unsigned long ul; 

string = "lOO0el3 e"; 

printf("string = %s\n", string); 

ul = strtoul(string, &stopstring, BASE); 

printf(" strtoul = %ld (base %d)\n", ul, BASE); 

printf(" Stopped scan at %s\n\n", stopstring); 

return 0; 

/**************************************************************************** 

The output should be: 

string = 100Oel3 e 
strtoul = 8 (base 2) 

Stopped scan at el3 e 

****************************************************************************/ 



“atof — Convert Character String to Float” on page 63 
“atoi — Convert Character String to Integer” on page 65 
“atol — Convert Character String to Long Integer” on page 67 
“_atold — Convert Character String to Long Double” on page 69 

“strtod — Convert Character String to Double” on page 621 

“strtol — Convert Character String to Long Integer” on page 625 

“strtold — Convert String to Long Double” on page 627 
“_ul toa — Convert Unsigned Long Integer to String” on page 716 
“wcstod — Convert Wide-Character String to Double” on page 778 
“wcstol — Convert Wide-Character to Long Integer” on page 782 
“wcstoul — Convert Wide-Character String to Unsigned Long” on page 786 
“<stdlib.h>” on page 816 


630 VisualAge C++ C Library Reference 




strupr 


strupr — Convert Lowercase to Uppercase 

Format linclude <string.h> 

char *strupr(char *string ); 

Description Language Level: Extension 

strupr converts any lowercase letters in string to uppercase. Other characters are 
not affected. 


Return Value strupr returns a pointer to the converted string. There is no error return. 



This example makes a copy in all-uppercase of the string "DosWrite", and then prints 
the copy. 

#include <string.h> 

#include <stdio.h> 


int main(void) 

{ 

char *string = "DosWrite"; 
char *copy; 

copy = strupr(strdup(string)); 
printf("This is a copy of the string\n"); 
printf("with all letters capitalized: %s\n", copy); 
return 0; 

/**************************************************************************** 

The output should be: 

This is a copy of the string 

with all letters capitalized: DOSWRITE 

****************************************************************************/ 



“strlwr — Convert Uppercase to Lowercase” on page 594 
“_toascii - _tolower - _toupper — Convert Character” on page 673 
“tolower - toupper — Convert Character Case” on page 676 
“towlower - towupper — Convert Wide Character Case” on page 677 
“<sUing.h>” on page 818 
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strxfrm — Transform String 

Format linclude <string.h> 

size_t strxfrm(char *strl, const char *str2, size_t n ); 

Description Language Level: ANSI, SAA, XPG4 

strxfrm transforms the string pointed to by str2 and places the resulting string into 
the array pointed to by strl. The transformation is determined by the program's 
locale. The transformed string is not necessarily readable, but can be used with the 
strcmp or strncmp functions. 

The transformation is such that, if strcmp or strncmp were applied to the two 
transformed strings, the results would be the same as applying strcol 1 to the two 
corresponding untransformed strings. 

No more than n bytes are placed into the area pointed to by strl , including the 
terminating null byte. If n is 0, strl can be a null pointer. 

Return Value strxfrm returns the length of the transformed string (excluding the null byte). 

When n is 0 and strl is a null pointer, the length returned is one less than the 
number of bytes required to contain the transformed string. If an error occurs, 
strxfrm function returns (size_t)-l and sets errno to indicate the error. 

Notes: 

1. The string returned by strxfrm contains the weights for each order of the 
characters within the string. As a result, the string returned may be longer than 
the input string; it does not contain printable characters. 

2. strxfrm calls malloc when the LC_COLLATE category specifies backward on 
the order_start keyword, the substitute keyword is specified, or the locale 
has one-to-many mapping. If malloc fails, strxfrm also fails. 

3. If the locale supports double-byte characters (MB_CUR_MAX specified as 2), 
strxfrm validates the multibyte characters. (Previously it did not validate the 
string.) strxfrm will fail if the string contains invalid multibyte characters. 

4. If MB_CUR_MAX is defined as 2, and no collation is defined for DBCS chars 
in the current locale, the DBCS characters will collate after the single-byte 
characters. 

This example uses strxfrm to transform two different strings that have the same 
collating weight. It then calls strcmp to compare the new strings. 
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linclude <stdlib.h> 
linclude <stdio.h> 
linclude <locale.h> 

int main(void) 

{ 

char *stringl = "stride ng1"; 
char *string2 = "stri*ngl"; 
char *newstringl, *newstring2; 
int lengthl, length2; 

if (NULL == setlocale(LC_ALL, LC_C_FRANCE)) { 
printf("setlocale fai1ed.\n"); 
exit(EXIT_FAILURE); 

} 

1 engthl=strxfrm(NULL, stringl, 0); 

1 ength2=strxfrm(NULL, string2, 0); 

if (NULL == (newstringl = calloc(lengthl + 1, 1)) || 

NULL == (newstring2 = calloc(length2 + 1, 1))) { 
printf("insufficient memory\n"); 
exit(EXIT_FAILURE); 

} 

if ((strxfrm(newstringl, stringl, lengthl + 1) != lengthl) || 

(strxfrm(newstring2, string2, length2 + 1) != Iength2)) { 
printf("error in string processing\n"); 
exit(EXIT_FAILURE); 

} 

if (0 != strcmp(newstringl, newstring2)) 
printf("wrong results\n"); 
el se 

printf("correct results\n"); 
return 0; 

^■k-k-kk-kick-k-k-k-k-kick-k-k'k'k-k-kick-k-kick-k-k'k-k-k-kick-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-kk-kick-kick-k-k-k-k-k-k-k'k-k-kick-k-kick-k-k 

The output should be similar to : 
correct results 

■ kick-k-k-k'k-k-kick-k-k-k-k'k-k-k'k-k-kick-k-kick-k-k'k'k-k-k-k-k-k-kick-k-k'k'k-k-kick'k-kick'k-k-k'k-k-kick-k-k-k-k-k-k-k'k-k-kick-k-kick-kj 

1 


• “localeconv — Retrieve Information from the Environment” on page 381 

• “setl ocal e — Set Locale” on page 530 

• “strcmp — Compare Strings” on page 567 

• “strcoll — Compare Strings Using Collation Rules” on page 571 

• “strncmp — Compare Strings” on page 597 

• “wcsxfrm — Transform Wide-Character String” on page 790 

• “<string.h>” on page 818 
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swab — Swap Adjacent Bytes 

Format linclude <stdlib.h> 

void swab(char *source, char *destination , int n); 

Description Language Level: Extension 

swab copies n bytes from source, swaps each pair of adjacent bytes, and stores the 
result at destination. The integer n should be an even number to allow for 
swapping. If n is an odd number, a null character (\0) is added after the last byte. 

swab is typically used to prepare binary data for transfer to a machine that uses a 
different byte order. 

Note: In earlier releases of C Set ++, swab began with an underscore (_swab). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _swab to swab for you. 

Return Value There is no return value. 

This example copies n bytes from one location to another, swapping each pair of 
adjacent bytes: 

linclude <stdlib.h> 
linclude <stdio.h> 

int main(void) 

{ 

char from[20] = "hTsii s atsirgn..x 
char to [20] ; 

swab(from, to, 19); /* swap bytes */ 

printf("%s\n", to); 

return 0; 

/**************************************************************************** 

The output should be: 

This is a string.. 

■k-k-k-k'k-k-k'k-k-klc-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k'k-k-klc-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k'k/ 

} 

• “fgetc — Read a Character” on page 225 

• “fputc — Write Character” on page 252 

• “<stdlib.h>” on page 816 
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swprintf — Format and Write Wide Characters to Buffer 

Format linclude <wchar.h> 

int swprintf(wchar_t *wcbuffer, size_t n, 

const wchar_t *format, argument-list ); 

Description Language Level: ANSI 93 

swprintf formats and stores a series of wide characters and values into the 
wide-character buffer wcsbuffer. swpri ntf is equivalent to spri ntf, except that it 
operates on wide characters. 

The value n specifies the maximum number of wide characters to be written, 
including the terminating null character. 

swprintf converts each entry in the argument-list according to the corresponding 
wide-character format specifier in format. The format has the same form and 
function as the format string for printf, with the following exceptions: 

• %c (without an 1 prefix) converts an integer argument to wchar_t, as if by calling 
mbtowc. 

• %lc converts a wint_t to wchar_t. 

• %s (without an 1 prefix) converts an array of multibyte characters to an array of 
wchar_t, as if by calling mbrtowc. The array is written up to, but not including, 
the terminating null character, unless the precision specifies a shorter output. 

• %1 s writes an array of wchar_t. The array is written up to, but not including, the 
terminating null character, unless the precision specifies a shorter output. 

If you specify a null string for the %s or %ls format specifier, swprintf prints (null). 

For a complete description of format specifiers, see “printf — Print Formatted 
Characters” on page 461. 

A null wide character is added to the end of the wide characters written; the null 
wide character is not counted as part of the returned value. If copying takes place 
between objects that overlap, the behavior is undefined. 

In extended mode, swpri ntf also converts floating-point values of NaN and infinity 
to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 
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Return Value swprintf returns the number of bytes written in the array, not counting the 
terminating null wide character. 

This example uses swpri ntf to format and print several values to buffer. 

linclude <wchar.h> 
linclude <stdio.h> 

Idefine BUF_SIZE 100 

int main(void) 

{ 

wchar_t wcsbuf[BUF_SIZE]; 
wchar_t wstring[] = L"ABODE"; 
int niim; 

num = swprintf(wcsbuf, BUF_SIZE, L"%s", "xyz"); 
num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%ls", wstring); 
num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%i", 100); 
printf("The array wcsbuf contains: \"%ls\"\n", wcsbuf); 
return 0; 

I ***********************************************'****'******'*'**'******'***'*'*'***'*'* 
The output should be similar to : 

The array wcsbuf contains: "xyzABCDElOO" 

i 




“printf — Print Formatted Characters” on page 461 
“spri ntf — Print Formatted Data to Buffer” on page 554 
“swscanf — Read Wide Characters from Buffer” on page 637 
“vswprintf — Format and Write Wide Characters to Buffer” on page 745 
“<wchar.h>” on page 821 
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swscanf — Read Wide Characters from Buffer 

Format linclude <wchar.h> 

int swscanf(const wchar_t *wcsbuffer , const wchar_t * format , 
argument-list); 

Description Language Level: ANSI 93 

swscanf reads wide data from wcsbuffer into the locations given by 
argument-list, swscanf is equivalent to sscanf, except that it operates on wide 
characters. 

Each argument in the argument-list must point to a variable with a type that 
corresponds to a type specifier in format. The format has the same form and 
function as the format string for scanf, with the following exceptions: 

• %c (with no 1 prefix) converts one or more wchar_t characters (depending on 
precision) to multibyte characters, as if by calling wcrtomb. 

• %1 c converts one or more wchar_t characters (depending on precision) to an 
array of wchar_t. 

• %s (with no 1 prefix) converts a sequence of non-white-space wchar_t characters 
to multibyte characters, as if by calling wcrtomb. The array includes the 
terminating null character. 

• %1 s copies an array of wchar_t, including the terminating null wide character, to 
an array of wchar_t. 

For a complete description of format specifiers, see “scanf — Read Data” on 
page 517. 

When swscanf reaches the end of the wide character string, it stops parsing and 
returns a value as indicated below (this behavior is the same as sscanf). If copying 
takes place between objects that overlap, the behavior is undefined. 

Return Value swscanf returns the number of input items that were successfully converted and 

assigned. The value does not include fields that were read but not assigned. If an 
input failure (such as the end of the string) is encountered before any conversion, 
swscanf returns EOF. 


Chapter 3. Library Functions 637 



swscanf 



This example uses swscanf to scan in wide characters, and then prints them. 

#include <wchar.h> 

#include <stdio.h> 

int main(void) 

{ 

wchar_t *tokenstring = L"xyz aAaBaCaDaE a 1234"; 

char string[20]; 

wchar_t wstring[20]; 

wchar_t wc; 

int i; 

int num; 


num = swscanf(tokenstring, L"%s %ls %lc %d", string, wstring, &wc, &i); 

printf("string = %s\n", string ); 

printf("wstring = %ls\n", wstring ); 

printf("wc = %lc\n", wc ); 

printf("i = %d\n", i ); 

printf("total number of fields scanned: %i\n", num); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

string = xyz 

wstring = aAaBaCaDaE a 

wc =1 

i = 234 

total number of fields scanned: 4 

****************************************************************************/ 

} 



“scanf — Read Data” on page 517 
“sscanf — Read Data” on page 559 

“swpri ntf — Format and Write Wide Characters to Buffer” on page 635 
“<wchar.h>” on page 821 
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system — Invoke the Command Processor 

Format linclude <stdlib.h> 

int system(char *string ); 

Description Language Level: ANSI, SAA, XPG4, Extension 

system passes the command string to a command processor to be run. The 
command processor specified in the COMSPEC environment variable is first searched 
for. If it does not exist or is not a valid executable file, the default command 
processor, CMD.EXE, is searched for in the current directory and in all the directories 
specified in the PATH environment variable. 

If the specified command is the name of an executable file created from a C program, 
full initialization and termination are performed, including automatic flushing of 
buffers and closing of files. To pass information across a system function, use a 
method of interprocess communication like pipes or shared memory. 

You can also use system to redirect standard streams using the redirection operators 
(the angle brackets), for example: 

rc = system("cprogram < in.file"); 

The defaults for the standard streams will be whatever the standard streams are at the 
point of the system call; for example, if the root program redirects stdout to 
file.txt, a printf call in a C module invoked by a system call will append to 
file.txt. 


Return Value If the argument is a null pointer, system returns nonzero if a command processor 
exists, and 0 if it does not. system returns the the return value from the command 
processor if it is successfully called. If system cannot call the command processor 
successfully, the return value is -1 and errno is set to one of the following values: 


Value 

ENOCMD 

ENOMEM 

EOS2ERR 


Meaning 

No valid command processor found. 

Insufficient memory to complete the function. 

A system error occurred. Check _doserrno for the specific OS/2 
error code. 
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This example shows how to use system to execute the OS/2 command dir c:\. 
#include <stdlib.h> 

int main(void) 

{ 

int rc; 


rc = system("dir c:\\"); 
return rc; 


/* The output should be a listing of the root directory on the c: drive */ 

} 



“exit — End Program” on page 204 
“_exi t — End Process” on page 205 
“<process.h>” on page 812 
“<stdlib.h>” on page 816 
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_sxchg — Exchange Integer Value with Memory 

Format linclude <builtin.h> 

short _Builtin _sxchg(volatile short*lockptr , short value); 

Description Language Level: Extension 

_sxchg puts the specified value in the memory location pointed to by lockptr , and 

returns the value that was previously in that location. 

Use this function to implement fast-RAM semaphores to serialize access to a critical 
resource (so that only one thread can use it at a time). You can also use OS/2 
semaphores to serialize resource access, but they are slower. Typically you would 
create both a fast-RAM semaphore and an OS/2 semaphore for the resource. For 
more details about OS/2 semaphores and how to use them, see the Control Program 
Guide and Reference. 

To implement a fast-RAM semaphore, allocate a volatile memory location lockptr 

(for_sxchg, it must be a short), and statically initialize it to 0 to indicate that the 

resource is free (not being used). To give a thread access to the resource, call 

_sxchg from the thread to exchange a non-zero value with that memory location. If 

_sxchg returns 0, the thread can access the resource; it has also set the memory 

location so that other threads can tell the resource is in use. When your thread no 
longer needs the resource, call_sxchg again to reset the memory location to 0. 

If_sxchg returns a non-zero value, another thread is already using the resource, and 

the calling thread must wait for access. You could then use the OS/2 semaphore to 
inform your waiting thread when the resource is unlocked by the thread currently 
using it. 

It is important that you set the memory to a non-zero value when you are using the 
resource. You can use the same non-zero value for all threads, or a unique value for 
each. 

Note: _sxchg is a built-in function, which means it is implemented as an inline 

instruction and has no backing code in the library. For this reason: 

• You cannot take the address of_sxchg. 

• You cannot parenthesize a call to_sxchg. (Parentheses specify a call to the 

function's backing code, and_sxchg has none.) 

Return Value _sxchg returns the previous value stored in the memory location pointed to by 

lockptr. 
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This example creates five separate threads, each associated with a State. At most 
two threads can have a State of Eating at the same time. When a thread calls 
PickUpChopSticks, that function checks the states of the preceding threads to make 

sure they are not already Eating, If the call to_ sxchg is successful, the thread has 

locked the Lock semaphore and can change its State to Eating. It then calls_ sxchg 

a second time to unlock the semaphore, and returns. 


If_sxchg cannot lock the semaphore, another thread has it locked. The current 

thread then suspends itself briefly with DosSleep and tries again. The semaphore is 
used to ensure that two threads cannot simultaneously change their State to Eating, 
which would cause a deadlock. (Note that although the semaphore solves the 
problem of deadlock, it is not an optimal solution; some threads may never get the 
semaphore or the State of Eating.) 

Note: You must compile this example with the multithread (/Gm) option. The 
example runs in an infinite loop; press Ctrl-C to end it. 

#pragma strings(readonly) 

#define INCL_D0S 
#include <os2,h> 

#include <stdlib.h> 

#include <stdio.h> 

#include <bui1tin.h> 

typedef enum { 

Thinking, 

Eating. 

Hungry 
} States; 

#define UNLOCKED 0 
#define LOCKED 1 
#define NUM_PHILOSOPHERS 5 

static volatile short Lock; 

static States State[NUM_PHILOSOPHERS]; 

static const int NameMap[NUM_PHILOSOPHERS] = {0, 1, 2, 3, 4}; 
static const char * const Names[NUM_PHILOSOPHERS] = {"Plato", 

"Socrates", 

"Kant", 

"Hegel", 

"Nietsche"}; 
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void PickUpChopSticks(int Ident); 
void PutDownChopSticks(int Ident); 
void Think(int Ident); 
void Eat(int Ident); 

void _0ptlink StartPhilosopher(void *pldent); 

void _0ptlink StartPhilosopher(void *pldent) 

{ 

int Ident = *(int *)pldent; 
while (1) { 

State[Ident] = Hungry; 

printf("%s hungry.\n", Names[Ident]); 

PickUpChopSticks(Ident); 

Eat(Ident); 

PutDownChopSticks(Ident); 

Think(Ident); 



int main(int argc, char *argv[], char *envp[]) 

{ 

int i; 

unsigned long tid; 

for (i = 0; i < NUM_PHILOSOPHERS; i++) { 

tid = _beginthread(StartPhilosopher, NULL, 8192, (void *)&NameMap[i]); 
if (tid == -1) { 

printf("Unable to start %s.\n", Names[i]); 

} 

el se { 

printf("%s started with Thread Id = %d.\n". Names[i], tid); 


DosWaitThread(&tid, DCWW_WAIT); 
return 0; 


void PickUpChopSticks(int Ident) 

{ 

while (1) { 

if (State[(Ident + NUM_PHILOSOPHERS - 1) % NUM_PHILOSOPHERS] != Eating && 
State[(Ident + 1) % NUM_PHILOSOPHERS] != Eating && 

!_sxchg(&Lock, LOCKED)) { 

State[Ident] = Eating; 

_sxchg(&Lock, UNLOCKED); 

return; 

} 
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el se { 

DosSleep(l); 

} 

} 

} 


void PutDownChopSticks(int Ident) 

{ 

State[Ident] = Thinking; 

} 

void Eat(int Ident) 

{ 

printf("%s eating.\n". Names[Ident]); 
DosSleep(l); 


void Think(int Ident) 

{ 

printf("%s thinking.\n", Names[Ident]); 
DosSleep(l); 


/**************************************************************************** 

The output should be similar to : 

Plato started with Thread Id = 2. 

Socrates started with Thread Id = 3. 

Kant started with Thread Id = 4. 

Hegel started with Thread Id = 5. 

Nietsche started with Thread Id = 6. 

Plato hungry. 

Plato eating. 

Socrates hungry. 

Kant hungry. 

Kant eating. 

Hegel hungry. 

Nietsche hungry. 

Kant thinking. 

Plato thinking. 

Plato hungry. 

Plato eating. 

Kant hungry. 

Kant eating. 

****************************************************************************/ 



“_cxchg — Exchange Character Value with Memory” on page 134 

“_lxchg — Exchange Integer Value with Memory” on page 397 

“<builtin.h>” on page 801 
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tan — Calculate Tangent 

Format linclude <math.h> 

double tan(double x ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

tan calculates the tangent of x, where x is expressed in radians. If x is too large, a 
partial loss of significance in the result can occur. 

Return Value tan returns the value of the tangent of x. 

This example computes x as the tangent of it/4. 

#include <math.h> 

int main(void) 

{ 

double pi,x; 

pi = 3.1415926; 
x = tan(pi/4.0); 

printf("tan( %lf ) is %lf\n", pi/4, x); 
return 0; 

/**************************************************************************** 

The output should be: 

tan( 0.785398 ) is 1.000000 

****************************************************************************/ 

i 

• “atan - atan2 — Calculate Arctangent” on page 61 

• “cos — Calculate Cosine” on page 111 

• “_fpatan — Calculate Arctangent” on page 246 

• “_fptan — Calculate Tangent” on page 251 

• “sin — Calculate Sine” on page 543 

• “tanh — Calculate Hyperbolic Tangent” on page 646 

• “<math.h>” on page 811 
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tanh — Calculate Hyperbolic Tangent 

Format linclude <math.h> 

double tanh(double x) ; 

Description Language Level: ANSI, SAA, POSIX, XPG4 

tanh calculates the hyperbolic tangent of x, where x is expressed in radians. 

Return Value tanh returns the value of the hyperbolic tangent of x. The result of tanh cannot 
have a range error. 

This example computes x as the hyperbolic tangent of tt/4. 
linclude <math.h> 

int main(void) 

{ 

double pi,x; 

pi = 3.1415926; 
x = tanh(pi/4); 

printf("tanh( %lf ) = %lf\n", pi/4, x); 
return 0; 

/•k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-kle-k-k'k-k-klck-k-k-k-k-k-kick-k-k-k 

The output should be: 
tanh( 0.785398 ) = 0.655794 

} 

• “atan - atan2 — Calculate Arctangent” on page 61 

• “cosh — Calculate Hyperbolic Cosine” on page 112 

• “_fpatan — Calculate Arctangent” on page 246 

• “_fptan — Calculate Tangent” on page 251 

• “sinh — Calculate Hyperbolic Sine” on page 544 

• “tan — Calculate Tangent” on page 645 

• “<math.h>” on page 811 
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_tcal1oc — 

Format 

Description 


Return Value 



Reserve Tiled Storage Block 

linclude <stdlib.h> /* also in emailoc.h> */ 
void *_tcal loc(size_t number, size_t size) 

Language Level: Extension 

_tcal 1 oc allocates tiled memory for an array of number elements, each of length 
size bytes, and initializes all bits of each element to 0. 

To use _tcal 1 oc, you must compile with the /Gt compiler option. This option maps 
all cal 1 oc calls to _tcal 1 oc (you can also call _tcal 1 oc explicitly). 

Note: The /Gt option maps all calls to regular memory management functions to 
their tiled versions. To prevent a call from being mapped, parenthesize the function 
name. 

_tcal 1 oc works just like cal 1 oc except that it allocates tiled memory instead of 
regular memory. Tiled memory will not cross 64K boundaries, as long as the object 
is less than 64K in size. Objects larger than 64K in size will cross 64K boundaries. 

If you have objects that may be accessed by 16-bit code, you should store them in 
tiled memory. Tiled memory is limited to 512 MB per process. 

You can also create your own heaps of tiled memory. See “Memory Management” in 
the Programming Guide for more information. 

A debug version of this function, _debug_tcal loc, is also available. Use the /Tm 
compiler option to map _tcal 1 oc calls to _debug_tcal 1 oc. 

_tcal 1 oc returns a pointer to the allocated tiled memory. If not enough storage is 
available, or if num or size is 0, _tcal loc returns NULL. 

This example allocates tiled memory for an array of 100 elements of size char. 

Note: You must compile this example with the /Gt option to enable tiled memory. 
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#include <stdlib.h> 

int main(void) 

{ 

char *memoryPtr; 

if (NULL != (memoryPtr = calloc(100, sizeof(char)))) 

puts("Successfully allocated 100 char of tiled memory."); 
el se 

puts("Could not allocate tiled memory."); 
free(memoryPtr); 
return 0; 

/i(ic-k‘k-k-k‘k-k-k‘k-k-k-k-ki< , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k-k-k-k‘J(-k-k-k-k-k‘k-k-k‘k-k-ki(-k-k‘k-k-k-k 

The output should be similar to : 

Successfully allocated 100 char of tiled memory. 

■k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-kle-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-klck-k-k-k-klck-k-k-k-k/ 

} 



• “cal loc — Reserve and Initialize Storage” on page 80 

• “_debug_cal loc — Allocate and Initialize Memory” on page 139 

• “_debug_tcal loc — Reserve and Initialize Tiled Memory” on page 149 

• “_tdump_al 1 ocated — Get Information about Allocated Tiled Memory” on 
page 649 

• “_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

• “_tfree — Free Tiled Storage Block” on page 659 

• “_theapmin — Release Unused Tiled Memory” on page 663 

• “_tmal loc — Reserve Tiled Storage Block” on page 667 

• “_trealloc — Reallocate Tiled Storage Block” on page 679 

• “_ucal 1 oc — Reserve and Initialize Memory from User Heap” on page 686 

• “Differentiating between Memory Management Functions” on page 28 

• Managing Memory in the Programming Guide 

• “<malloc.h>” on page 810 

• “<stdlib.h>” on page 816 
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_tdump_allocated — Get Information about Allocated Tiled Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void _tdump_allocated(int nbytes ); 

Description Language Level: Extension 

_tdump_allocated prints information to stderr about each tiled memory block that 
is currently allocated and was allocated using the tiled debug memory management 
functions (_debug_tcal loc, _debug_tmal loc, and so on). 

_tdump_al 1 ocated works just like _dump_al 1 ocated, but displays information about 
tiled memory instead of regular memory. 

Use nbytes to specify how many bytes of each memory block are to be printed. If 
nbytes is: 

Negative value Prints all bytes of each block. 

0 Prints no bytes. 

Positive value Prints the specified number of bytes or the entire block, whichever 
is smaller. 

_tdump_al 1 ocated prints the information to stderr by default. You can change the 
destination with the _set_crt_msg_handl e function. 

Call _tdump_al 1 ocated at points in your code where you want a report of the 
currently allocated memory. For example, a good place to call _tdump_al located is 
a point where most of the memory is already freed and you want to find a memory 
leak, such as at the end of a program. 

You can also use _tdump_al 1 ocated_del ta to display information about only the 
tiled memory that was allocated since the previous call to _tdump_al 1 ocated or 
_tdump_al1ocated_delta. 

To use _tdump_al located and the tiled debug versions of the memory management 
functions, specify the /Tm /Gt compiler options, the debug memory and tiled memory 
compiler options (/Tm /Gt). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

Return Value There is no return value. 
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This example allocates some memory and then calls _tdump_al located to display 
information about the allocated blocks. 


Note: You must compile this example with the /Tm /Gt options. 

#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 


int main(void) 

{ 

char *ptrl; 

if (NULL == (ptrl = malloc(lO))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptrl, 'a', 5); 

_tdump_al1ocated(10); 
free(ptrl); 
return 0; 


/**************************************************************************** 

The output should be similar to : 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0x00080120 Size: OxOOOOOOOA (10) 

This memory block was (re)al1ocated at line number 9 in _tdump_alloc.c. 
Memory contents: 61616161 61AAAAAA AAAA [aaaaaeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


-k-k-k-ki(-k-k‘k-k-k‘k-k-k‘k-k-k , k'k-k‘k-k-k‘k-k-k‘k-k-ki(-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-ki(-ki<‘k-k-k‘k-k-k‘k-k-k , k'k-k‘k-k-k‘k-k-k‘k-k-k^ 

} 

“_debug_tcal loc — Reserve and Initialize Tiled Memory” on page 149 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_theapmin — Release Unused Tiled Memory” on page 153 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 
“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_ s et_crt_msg_handl e — Change Runtime Message Output Destination” on 
page 526 

“_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

“_udump_al located — Get Information about Allocated Memory in Heap” on 
page 699 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “Debugging Your Heaps” in the Programming Guide 

• “<malloc.h>” on page 810 
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“<stdlib.h>” on page 816 
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tdump allocated delta — Get Information about Allocated Tiled Memory 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void _tdump_allocated_delta(int nbytes ); 

Description Language Level: Extension 

For the heap you specify, _tdump_al 1 ocated_del ta prints information to stderr 
about each tiled memory block allocated by a tiled debug memory management 
function (_debug_tmal 1 oc and so on) since the last call to _tdump_al 1 ocated_del ta 
or _tdump_al 1 ocated. 

_tdump_allocated_del ta and _tdump_al 1 ocated print the same type of information 
to stderr, but _tdump_al located displays information about all blocks that have 
been allocated since the start of your program. 

_tdump_al 1 ocated_del ta works just like _dump_al 1 ocated_del ta, except that it 
displays information about tiled memory instead of regular memory. 

Use nbytes to specify how many bytes of each memory block are to be printed. If 
nbytes is: 

Negative value Prints all bytes of each block. 

0 Prints no bytes. 

Positive value Prints the specified number of bytes or the entire block, whichever 
is smaller. 

_tdump_al 1 ocated_del ta prints the information to stderr by default. You can 
change the destination with the _set_crt_msg_handl e function. 

To use _tdump_al 1 ocated_del ta and the tiled debug versions of the memory 
management functions, specify the debug memory and tiled memory compiler options 
(/Tm /Gt). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

Return Value There is no return value. 

This example allocates some memory and calls _tdump_al located to print 
information about the allocated blocks. It then allocates more memory, and calls 
_tdump_all ocated_del ta to print information about the blocks allocated since the 
call to _tdump_al 1 ocated. 

Note: You must compile this example with the /Tm /Gt options. 
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#include <stdlib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *ptrl, *ptr2; 

if (NULL == (ptrl = malloc(lO))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptrl, 'a', 5); 

_tdump_allocated(10); 

if (NULL == (ptr2 = mal1oc(20))) { 

puts("Could not allocate memory block."); 
exit(EXIT_FAILURE); 

} 

memset(ptr2, 'b', 5); 

_tdump_allocated_delta(10); 

free(ptrl); 

free(ptr2); 

return 0; 

/**************************************************************************** 
The output should be similar to : 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0x00080120 Size: 0xO000O0OA (10) 

This memory block was (re)allocated at line number 8 in _tdump_all_d.c. 
Memory contents: 61616161 61AAAAAA AAAA [aaaaaeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0x00080160 Size: 0x00000014 (20) 

This memory block was (re)allocated at line number 15 in _tdump_all_d.c. 
Memory contents: 62626262 62AAAAAA AAAA [bbbbbeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


****************************************************************************/ 

} 


“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_debug_tcal 1 oc — Reserve and Initialize Tiled Memory” on page 149 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_theapmi n — Release Unused Tiled Memory” on page 153 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
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• “_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 

• “_tdump_al 1 ocated — Get Information about Allocated Tiled Memory” on 
page 649 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “Debugging Your Heaps” in the Programming Guide 

• “<malloc.h>” on page 810 

• “<stdlib.h>” on page 816 
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tel 1 — Get Pointer Position 


Format 

Description 

Return Value 



linclude <io.h> 

long _tell(int handle); 

Language Level: Extension 

_tel 1 gets the current position of the file pointer associated with handle. The 
position is the number of bytes from the beginning of the file. 

_tel 1 returns the current position. A return value of -1L indicates an error, and 

errno is set to one of the following values: 

Value Meaning 

EBADF The file handle is not valid. 

EOS2ERR The call to the operating system was not successful. 

On devices incapable of seeking (such as screens and printers), the return value is 
-1L. 


This example opens the file tell ,dat. It then calls _t el 1 to get the current position 
of the file pointer and report whether the operation is successful. The program then 
closes tel 1,dat. 

#include <io.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <fcntl.h> 

Idefine FILENAME "tell.dat" 

int main(void) 

{ 

long filePtrPos; 
int fh; 

printf("Creating fi1e.\n"); 
systemfecho Sample Program > " FILENAME); 
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if (-1 == (fh = open(FILENAME, 0_RDWR|0_APPEND))) { 
perror("Unable to open " FILENAME); 
remove(FILENAME); 
return EXIT_FAILURE; 

} 

/* Get the current file pointer position. */ 

if (-1 == (filePtrPos * _tell(fh))) { 
perror("Unable to tell"); 
close(fh); 
remove(FILENAME); 
return EXIT_FAILURE; 

} 

printf("File pointer is at position %d.\n", filePtrPos); 
close(fh); 
remove(FILENAME); 
return 0; 

/**************************************************************************** 

The output should be: 

Creating file. 

File pointer is at position 0. 

****************************************************************************/ 

} 



“fseek — Reposition File Position” on page 273 
“ftel 1 — Get Current Position” on page 283 
“1 seek — Move File Pointer” on page 393 
“<io.h>” on page 804 
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tempnam — Produce Temporary File Name 

Format linclude <stdio.h> 

char *tempnam(char *dir, char *prefix ); 

Description Language Level: XGG4, Extension 

tempnam creates a temporary file name in another directory. The prefix is the prefix 
to the file name, tempnam tests for the existence of the file with the given name in 
the following directories, listed in order of precedence: 

• If the TMP environment variable is set and the directory specified by TMP 
exists, the directory is specified by TMP. 

• If the TMP environment variable is not set or the directory specified by TMP 
does not exist, the directory is specified by the dir argument to tempnam. 

• If the dir argument is NULL, or dir is the name of nonexistent directory, the 
directory is pointed to by P_tmpdir (defined in <stdio.h>). 

• If P_tmpdir does not exist, the directory is the current working directory. 

Notes: 

1. Because tempnam uses malloc to reserve space for the created file name, you 
must free this space when you no longer need it. 

2. In earlier releases of C Set ++, tempnam began with an underscore (_tempnam). 
Because it is defined by the X/Open standard, the underscore has been removed. 
Lor compatibility, VisualAge C++ will map _tempnam to tempnam for you. 

Return Value tempnam returns a pointer to the temporary name, if successful. If the name cannot 
be created or it already exists, tempnam returns the value NULL. 
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This example creates a temporary file name using the directory a:\tmp: 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

char *namel; 



if ((namel = tempnam("d:\\tmp", "stq")) != NULL) 

printf("%s is safe to use as a temporary file.\n", namel); 
el se { 

printf("Cannot create unique fi 1 ename\n"); 
return EXIT_FAILURE; 

} 

return 0; 

/•k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-klck-k-k-k-klck-k-k-k-k-k 

The output should be similar to: 

D:\tmp\stqU3CP2.C2T is safe to use as a temporary file. 

■kle-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-kle-k-k'k-k-k-k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-kle-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k/ 

) 

• “mal loc — Reserve Storage Block” on page 403 

• “_rmtmp — Remove Temporary Files” on page 513 

• “tmpf i 1 e — Create Temporary File” on page 671 

• “tmpnam — Produce Temporary File Name” on page 672 

• “<stdio.h>” on page 815 
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tfree — Free Tiled Storage Block 


Format 

Description 


Return Value 



linclude <stdlib.h> /* also in <malloc.h> */ 
void _tfree(void *ptr ); 

Language Level: Extension 

_tfree frees the tiled memory pointed to by ptr that has been allocated by one of 
the memory management functions. If ptr is NULL, then no action occurs. 

_tfree works just like free except that it frees tiled memory instead of regular 
memory. The _tfree function can only be used to free memory allocated by the 
tiled memory management functions (_tcalloc and so on). 

To use _tfree, you must compile with the /Gt compiler option. This option maps all 
free calls to _tfree (you can also call _tfree explicitly). 

Note: The /Gt option maps all calls to regular memory management functions to 
their tiled versions. To prevent a call from being mapped, parenthesize the function 
name. 

A debug version of this function, _debug_tfree is also available. Use the /Tm option 
to map _tfree calls to _debug_tfree. 

For more information about memory management, see “Managing Memory” in the 
Programming Guide. 

There is no return value. 

This example uses _tfree to free a block of tiled memory previously allocated by 
_tmal 1 oc. 

Note: You must compile this example with the /Gt option to enable tiled memory. 
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tfree 


#include <stdlib.h> 

int main(void) 

{ 

char *memoryPtr; 

if (NULL != (memoryPtr = mal1oc(100))) 

puts("Successfully allocated 100 bytes of tiled memory."); 
el se 

puts("Could not allocate tiled memory."); 
free(memoryPtr); 
return 0; 

/^■k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k 

The output should be similar to : 

Successfully allocated 100 bytes of tiled memory. 

■k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-kic-k-k-k-k-kick-k-k-k-k^ 

} 



“free — Release Storage Blocks” on page 263 

“_debug_free — Release Memory” on page 141 

“_debug_tfree — Release Tiled Memory” on page 151 

“_tcal loc — Reserve Tiled Storage Block” on page 647 

“_theapmin — Release Unused Tiled Memory” on page 663 

“_tmal loc — Reserve Tiled Storage Block” on page 667 

“_treal 1 oc — Reallocate Tiled Storage Block” on page 679 

“Differentiating between Memory Management Functions” on page 28 

“Managing Memory” in the Programming Guide 

“<malloc.h>” on page 810 

“<stdlib.h>” on page 816 
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theap_check 


theap check — Validate User Memory Heap 

Format linclude <stdlib.h> /* also in <malloc.h> */ 

void _theap_check(void); 

Description Language Level: Extension 

_theap_check checks all tiled memory blocks in the tiled runtime heap that have 
been allocated or freed using the tiled debug memory management functions 
(_debug_tcal loc, _debug_tmal loc, and so on). _theap_check checks that your 
program has not overwritten tiled memory that has been freed or that is outside the 
bounds of allocated tiled memory blocks. 

_theap_check works just like _heap_check except that it checks tiled memory 
instead of regular memory. 

When you call a tiled debug memory management function (such as 
_debug_tmal loc), it calls _theap_check automatically. You can also call 
_theap_check explicitly. Place calls to _theap_check throughout your code, 
especially in areas that you suspect have memory problems. 

Calling _theap_check frequently (explicitly or through the tiled debug memory 
functions) can increase your program's memory requirements and decrease its 
execution speed. To reduce the overhead of heap-checking, you can use the 
DDE4_HEAP_SKIP environment variable to control how often the functions check 
the heap. For example: 

SET DDE4_HEAP_SKIP= 10 

specifies that every tenth call to any debug memory function (regardless of the type 
or heap) checks the heap. Explicit calls to _theap_check are always performed. For 
more details on DDE4_HEAP_SKIP, see “Skipping Heap Checks” in the 
Programming Guide. 

To use _theap_check and the tiled debug versions of the memory management 
functions, specify the debug memory and tiled memory compiler options (/Tm /Gt). 

Note: The /Tm /Gt options map all calls to regular memory management functions to 
their tiled debug versions. To prevent a call from being mapped, parenthesize the 
function name. 

Return Value There is no return value. 
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theap_cheek 



This example allocates and frees memory from the tiled runtime heap, and then calls 
_theap_check to check the heap. 

Note: You must compile this example with the /Gt /Tm options to map the memory 
management functions to their tiled debug versions. 

#include <stdlib.h> 

#include <stdio.h> 


int main(void) 

{ 

char *ptr; 

if (NULL == (ptr = malloc(10))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

*(ptr - 1) = 'x 1 ; /* overwrites storage that was not allocated */ 

_theap_check(); 

free(ptr); 
return 0; 


/**************************************************************************** 

The output should be similar to : 

Header information of object 0x00080120 was overwritten at 0x0008011c. 

The first eight bytes of the memory block (in hex) are: AAAAAAAAAAAAAAAA. 
This memory block was (re)allocated at line number 8 in _theap_chec.c. 

Heap state was valid at line 8 of _theap_check.c. 
****************************************************************************/ 

} 



“_heap_check — Validate Default Memory Heap” on page 323 
“_debug_tcal loc — Reserve and Initialize Tiled Memory” on page 149 
“_debug_tfree — Release Tiled Memory” on page 151 
“_debug_theapmin — Release Unused Tiled Memory” on page 153 
“_debug_tmal 1 oc — Reserve Tiled Memory” on page 155 
“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 
“Differentiating between Memory Management Functions” on page 28 
“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“<malloc.h>” on page 810 
“<stdlib.h>” on page 816 
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theapmin 


_theapmin 

Format 

Description 


Return Value 



Release Unused Tiled Memory 

linclude <stdlib.h> /* also in <malloc.h> */ 
int _theapmin(void); 

Language Level: Extension 

_theapmin returns all unused tiled memory from the runtime heap to the operating 
system. _theapmin works just like _heapmin, except that it returns only tiled 
memory; _heapmin returns only regular memory. 

You can call _theapmi n explicitly, or specify the /Gt compiler option to map all 
_heapmi n calls to _theapmi n. 

Note: When you specify /Gt, all calls to regular debug memory management 
functions (calloc and so on) are mapped to their tiled equivalents. However, if you 
parenthesize the function calls, they are not mapped. 

A debug version of this function, _debug_theapmi n, is also available. Use the /Tm 
option to map _theapmi n calls to _debug_theapmi n. For more information about 
memory management, see “Managing Memory” in the Programming Guide. 

If successful, _theapmin returns 0; otherwise, it returns -1. 

This example allocates and frees memory from the tiled runtime heap, and then uses 
_theapmin to return any unused memory to the tiled heap. 

Note: You must compile this example with the /Gt option to enable tiled memory. 

#include <std1ib.h> 

#include <stdio.h> 

int main(void) 

{ 

char *ptr; 
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theapmin 


/* Allocate a large object from the system. */ 
if (NULL == (ptr = mal1oc(6OO0O))) { 

puts("Could not allocate memory block.\n"); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x 1 , 60000); 

/* The free will keep large object in runtime. */ 
free(ptr); 

/* _theapmin will attempt to return the freed object to the system. */ 
if (0 != _theapmin()) { 

puts("_debug_theapmin returns failed.\n"); 
exit(EXIT_FAILURE); 

} 

return 0; 



• “_debug_heapmi n — Release Unused Memory in the Default Heap” on 
page 143 

• “_debug_theapmin — Release Unused Tiled Memory” on page 153 

• “_heapmin — Release Unused Memory from Default Heap” on page 327 

• “_tcal loc — Reserve Tiled Storage Block” on page 647 

• “_tfree — Free Tiled Storage Block” on page 659 

• “_tmal loc — Reserve Tiled Storage Block” on page 667 

• “_trealloc — Reallocate Tiled Storage Block” on page 679 

• “_uheapmin — Release Unused Memory in User Heap” on page 709 

• “Differentiating between Memory Management Functions” on page 28 

• Memory Management in the Programming Guide 

• “<malloc.h>” on page 810 

• “<stdlib.h>” on page 816 
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threadstore 


threadstore — Access Thread-Specific Storage 

Format linclude <stdlib.h> 

void *_threadstore(void); 

Description Language Level: Extension 

_threadstore provides access to a private thread pointer that is initialized to NULL. 
You can assign any thread-specific data structure to this pointer. 

You can only use _threadstore in multithread programs (compiled with the /Gm+ 
option). 


Return Value _threadstore returns the address of the pointer to the defined thread storage space. 



This example uses _threadstore to point to storage that is local to the thread. It 
prints the address pointed to by _threadstore. 

Note: You must compile this example with the multithread option (/Gm+). 

#include <stdlib.h> 
line!ude <stdio.h> 


Idefine privateStore (*_threadstore()) 

void thread(void *dummy) 

{ 

privateStore = mal1oc(100); 

printf("The starting address of the storaged space is %p\n", privateStore); 

/* user must free storage before exiting thread */ 
free (privateStore); 

_endthread(); 


int main(void) 

{ 

i nt i; 


for (i = 0; i < 10; i++) 

_beginthread(thread, NULL, (unsigned) 32096, NULL); 
DosSleep(5O0OL); 
return 0; 



“_beginthread — Create New Thread” on page 71 
“_endthread — Terminate Current Thread” on page 195 
“<stdlib.h>” on page 816 
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time 


time — Determine Current Time 

Format linclude <time.h> 

time_t time(time_t *timeptr ); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

time determines the current calendar time, which is not necessarily the local time 
1 ocal time. 

Note: The time and date functions begin at 00:00:00 Universal Time, January 1, 
1970. 


Return Value time returns the current calendar time. The return value is also stored in the 

location given by timeptr. If timeptr is NULL, the return value is not stored. If the 
calendar time is not available, the value (time_t) (-1) is returned. 



This example gets the time and assigns it to Itime. ctime then converts the number 
of seconds to the current date and time. This example then prints a message giving 
the current time. 


#include <time.h> 
#include <stdio.h> 


int main(void) 

{ 

time_t Itime; 


time(&ltime); 

printf("The time is %s\n", ctime(&ltime)); 
return 0; 


/***9r**9c**9r**9c**9r**9c**9r**9r**9r**9c**9c**9c**9r**9c**9r**9c**9r**9c**9r**9c**9r**9c'**9r'**9r**9c 


The output should be similar to: 


The time is Thu Jan 12 11:38:37 1995 

****************************************************************************/ 



“asctime — Convert Time to Character String” on page 55 

“ctime — Convert Time to Character String” on page 129 

“gmtime — Convert Time” on page 321 

“localtime — Convert Time” on page 385 

“mktime — Convert Local Time” on page 438 

“_strtime — Copy Time” on page 617 

“<time.h>” on page 819 
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tmalloe 


_tmal1oc — 

Format 

Description 


Return Value 



Reserve Tiled Storage Block 

linclude <stdlib.h> /* also in emailoc.h> */ 
void _tmalloc(size_t size); 

Language Level: Extension 

_tmal loc allocates tiled memory for an object of size size , the value of which is 
indeterminate. 

To use _tmal 1 oc, you must compile with the /Gt compiler option. This option maps 
all mal 1 oc calls to _tmal 1 oc (you can also call _tmal 1 oc explicitly). 

Note: The /Gt option maps all calls to regular memory management functions to 
their tiled versions. To prevent a call from being mapped, parenthesize the function 
name. 

_tmal 1 oc works just like mal 1 oc except that it allocates tiled memory instead of 
regular memory. Tiled memory will not cross 64K boundaries, as long as the object 
is less than 64K in size. Objects larger than 64K in size are aligned on 64K 
boundaries, but will also cross 64K boundaries. If you have objects that may be 
accessed by 16-bit code, you should store them in tiled memory. 

Tiled memory from the Visual Age C++ runtime heap is limited to 512 MB per 
process. You can also create your own heaps of tiled memory, which can be larger 
in size. See Memory Management in the Programming Guide for more information. 

Memory allocated by _tmal 1 oc can only be freed using _tfree. 

A debug version of this function, _debug_tmal loc, is also available. Use the /Tm 
option to map all _tmal 1 oc calls to _debug_tmal 1 oc. 

_tmal 1 oc returns a pointer to the allocated tiled memory. If not enough storage is 
available, or if size is 0, _tmal loc returns NULL. 

This example uses _tmal loc to allocate 100 bytes of tiled memory. 

Note: You must compile this example with the /Gt option to enable tiled memory. 
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tmalloc 


#include <stdlib.h> 

int main(void) 

{ 

char *memoryPtr; 

if (NULL != (memoryPtr = mal1oc(100))) 

puts("Successfully allocated 100 bytes of tiled memory."); 
el se 

puts("Could not allocate tiled memory."); 
free(memoryPtr); 
return 0; 

/•k'k-kic-k-kle-k-k'k-k-k-k-klt'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k 

The output should be similar to: 

Successfully allocated 100 bytes of tiled memory. 

■k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-kic-k-k-k-k-kick-k-k-k-k j 

} 



• “_debug_mal 1 oc — Allocate Memory” on page 145 

• “_debug_tmal loc — Reserve Tiled Memory” on page 155 

• “mal loc — Reserve Storage Block” on page 403 

• “_tcal loc — Reserve Tiled Storage Block” on page 647 

• “_tdump_al 1 ocated — Get Information about Allocated Tiled Memory” on 
page 649 

• “_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

• “_tfree — Free Tiled Storage Block” on page 659 

• “_trealloc — Reallocate Tiled Storage Block” on page 679 

• “_umal 1 oc — Reserve Memory Blocks from User Heap” on page 717 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory in the Programming Guide 

• “<malloc.h>” on page 810 

• “<stdlib.h>” on page 816 
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_tmem_init 

Format 

Description 


Return Value 



tmem_init 


- Initialize Memory Functions for Subsystem DLL 

int _tmem_init(void); 

/* no header file - defined in runtime startup code */ 

Language Level: Extension 

_tmem_i n i t initializes the tiled memory functions for subsystem DLLs. (If your 
subsystem DLL does not use tiled memory, call _rmem_i ni t instead of _tmem_i ni t.) 
Although subsystems do not require a runtime environment (and therefore do not call 
_CRT_i ni t), they do require the library memory functions. For DLLs that do use a 
runtime environment, the memory functions are initialized with the environment by 
_CRT_i ni t. 

By default, all DLLs call the VisualAge C++ _DLL_Ini tTerm function, which in turn 
initializes the tiled memory functions for you. However, if you are writing your own 
subsystem _DLL_Ini tTerm function (for example, to perform actions other than 
memory initialization and termination), you must call _tmem_init from your version 
of _DLL_Ini tTerm before you can call any other library functions. 

If your DLL contains C++ code, you must also call _ctordtorlnit after _tmem_init 

to ensure that static constructors and destructors are initialized properly. 

_ctordtorlnit is defined in the runtime startup code as: 

void _ctordtorlnit(void); 

If the memory functions were successfully initialized, _tmem_init returns 0. A 
return code of -1 indicates an error. If an error occurs, an error message is written to 
file handle 2, which is the usual destination of stderr. 

• Building Subsystem DLLs in the Programming Guide 

• “_CRT_i nit — Initialize DLL Runtime Environment” on page 118 

• “_CRT_term — Terminate DLL Runtime Environment” on page 122 

• “_DLL_Ini tTerm — Initialize and Terminate DLL Environment” on page 170 

• “_rmem_init — Initialize Memory Functions for Subsystem DLL” on page 501 

• “_rmem_term — Terminate Memory Functions for Subsystem DLL” on page 507 

• “_tmem_term — Terminate Memory Functions for Subsystem DLL” on page 670 
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tmemterm 

_tmem_term 

Format 

Description 


Return Value 



- Terminate Memory Functions for Subsystem DLL 

int _tmem_term(void); 

/* no header file - defined in runtime startup code */ 

Language Level: Extension 

_tmem_term terminates the tiled memory functions for subsystem DLLs. It is only 
needed for DLLs that used tiled memory and that statically link to the runtime library. 

By default, all DLLs call the VisualAge C++ _DLL_InitTerm function, which in turn 
calls the termination functions for you. However, if you are writing your own 
_DLL_Ini tTerm function (for example, to perform actions other than memory 
initialization and termination), and your DLL statically links to the C runtime 
libraries, you need to call _rmem_term from your subsystem _DLL_Ini tTerm function. 
(For DLLs with a runtime environment, this termination is done by _CRT_term. If 
your subsystem DLL does not use tiled memory, call _rmem_term instead of 
_tmem_term.) 

If your DLL contains C++ code, you must also call _ ctordtorTerm before you call 

_tmem_term to ensure that static constructors and destructors are terminated correctly. 
_ctordtorTerm is defined in the runtime startup code as: 

void _ctordtorTerm(void); 

Once you have called _tmem_term, you cannot call any other library functions. 

If your DLL is dynamically linked, you cannot call library functions in the 
termination section of your _DLL_Ini tTerm function. If your termination routine 
requires calling library functions, you must register the termination routine with 
DosExitList. Note that all DosExitList routines are called before DLL termination 
routines. 

_tmem_term returns 0 if the memory functions were successfully terminated. A 
return value of -1 indicates an error. 

• Building Subsystem DLLs in the Programming Guide 

• “_CRT_i nit — Initialize DLL Runtime Environment” on page 118 

• “_CRT_term — Terminate DLL Runtime Environment” on page 122 

• “_DLL_InitTerm — Initialize and Terminate DLL Environment” on page 170 

• “_rmem_init — Initialize Memory Functions for Subsystem DLL” on page 501 

• “_rmem_term — Terminate Memory Functions for Subsystem DLL” on page 507 

• “_tmem_init — Initialize Memory Functions for Subsystem DLL” on page 669 
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tmpfile 


tmpf i 1 e — Create Temporary File 

Format linclude <stdio.h> 

FILE *tmpfi1e(void); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

tmpf i 1 e creates a temporary binary file. The file is automatically removed when it is 
closed or when the program is terminated. 

tmpf i 1 e opens the temporary file in wb+ mode. 


Return Value tmpfile returns a stream pointer, if successful. If it cannot open the file, it returns a 
NULL pointer. On normal termination (exit), these temporary files are removed. 

This example creates a temporary file, and if successful, writes tmpstring to it. At 
program termination, the file is removed. 

#include <stdio.h> 

#inc1ude <stdlib.h> 

FILE *stream; 

char tmpstringf] = "This is the string to be temporarily written"; 

int main(void) 

{ 

if (NULL == (stream = tmpfile())) { 

perror("Cannot make a temporary file"); 
return EXIT_FAILURE; 

} 

el se 

fprintf(stream, "%s", tmpstring); 
return 0; 

} 

• “fopen — Open Files” on page 243 

• “tmpnam — Produce Temporary File Name” on page 672 

• “tempnam — Produce Temporary File Name” on page 657 

• “_rmtmp — Remove Temporary Files” on page 513 

• “<stdio.h>” on page 815 
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tmpnam 


tmpnam — Produce Temporary File Name 

Format linclude <stdio.h> 

char *tmpnam(char *string); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

tmpnam produces a valid file name that is not the same as the name of any existing 
file. It stores this name in string. If string is NULL, tmpnam leaves the result in an 
internal static buffer. Any subsequent calls destroy this value. If string is not NULL, 
it must point to an array of at least L_tmpnam bytes. The value of L_tmpnam is defined 
in <stdio.h>. 

tmpnam produces a different name each time it is called within a module up to at least 
TMP_MAX (a value of at least 25) names. Note that files created using names returned 
by tmpnam are not automatically discarded at the end of the program. Files can be 
removed by the remove function. 

Return Value tmpnam returns a pointer to the name. If it cannot create a unique name; it returns 
NULL. 

This example calls tmpnam to produce a valid file name, 
linclude <stdio.h> 

int main(void) 

{ 

char *namel; 

if ((namel = tmpnam(NULL)) != NULL) 

printf("%s can be used as a file name.\n", namel); 
else 

printf("Cannot create a unique file name\n"); 
return 0; 

/•k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k'k-k‘k-k-k-k-k-k‘k-k1<‘k'k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k-k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k1<‘k 

The output should be similar to: 
d:\tmp\accO0O00.CTN can be used as a file name. 

■k-k-k-klc-k-k'k-k-k'k-k-k'k-k-klc-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-kick-k'k/ 

} 

• “fopen — Open Files” on page 243 

• “remove — Delete File” on page 495 

• “tempnam — Produce Temporary File Name” on page 657 

• “<stdio.h>” on page 815 




672 VisualAge C++ C Library Reference 



_toascii - 

Format 

Description 


Return Value 


toascii - _tolower - _toupper 


tolower - toupper — Convert Character 

linclude <ctype.h> 
int _toascii(int c); 
int _tolower(int c); 
int _toupper(int c); 

Language Level: Extension 

_toasci i converts c to a character in the ASCII character set, by setting all but the 
low-order 7 bits to 0. If c already represents an ASCII character, _toasci i does not 
change it. 

_tolower converts c to the corresponding lowercase letter, if possible. 

_toupper converts c to the corresponding uppercase letter, if possible. 

Important: Use _tolower and _toupper only when you know that c is uppercase 
A to Z or lowercase a to z, respectively. Otherwise the results are undefined. These 
functions are not affected by the current locale. 

These are all macros, and do not correctly handle arguments with side effects. 

For portability, use the tolower and toupper functions defined by the ANSI/ISO 
standard, instead of the _tolower and _toupper macros. 

_toasci i,_tol ower, and _toupper return the possibly converted character c. If 

the character passed to _toasci i is an ASCII character, _toasci i returns the 
character unchanged. There is no error return. 
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toascii - _tolower - _toupper 



This example prints four sets of characters. The first set is the ASCII characters 
having graphic images, which range from 0x21 through 0x7e. The second set takes 
integers 0x7f21 through 0x7f7e and applies the _toasci i macro to them, yielding the 
same set of printable characters. The third set is the characters with all lowercase 
letters converted to uppercase. The fourth set is the characters with all uppercase 
letters converted to lowercase. 


#include <stdio.h> 

#include <ctype.h> 

int main(void) 

{ 

int ch; 

printf("Characters 0x01 to 0x03, and integers 0x7f01 to 0x7fO3 mapped to\n"); 
printf("ASCII by _toascii() both yield the same graphic characters.\n\n"); 
for (ch = 0x01; ch <= 0x03; ch++) { 

printf("char 0x%.4X: %c ", ch, ch); 

printf("char _toascii(0x%.4X): %c\n", ch+0x7f00, ch+0x7f00); 

} 

printf("\nCharacters A, B and C converted to lower case and\n"); 
printf("Characters a, b and c converted to upper case.\n\n"); 
for (ch = 0x41; ch <= 0x43; ch++) { 

printf("_tolower(%c) = %c ", ch, _tolower(ch)); 
printf("_toupper(%c) = %c\n", ch+0x20, _toupper(ch+0x20)); 

} 

return 0; 

/**************************************************************************** 

The output should be: 

Characters 0x01 to 0x03, and integers 0x7f01 to 0x7f03 mapped to 
ASCII by _toascii() both yield the same graphic characters. 

char 0x0001: @ char _toascii(Ox7F01): @ 

char 0x0002; ® char _toascii(0x7F02): ® 

char 0x0003: v char _toascii(0x7F03): v 

Characters A, B and C converted to lower case and 

Characters a, b and c converted to upper case. 

_tolower(A) = a _toupper(a) = A 

_tolower(B) = b _toupper(b) = B 

_tolower(C) = c _toupper(c) = C 

} 



“i sal num to i sxdi gi t — Test Integer Value” on page 347 
“i sasci i — Test Integer Values” on page 350 
“_i scsym - _i scsymf — Test Integer” on page 356 
“tolower - toupper — Convert Character Case” on page 676 
“towlower - towupper — Convert Wide Character Case” on page 677 
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“<ctype.h>” on page 802 
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tolower - toupper — Convert Character Case 

Format linclude <ctype.h> 

int tolower(int C ); 
int toupper(int c); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

tol ower converts the uppercase letter C to the corresponding lowercase letter. 

toupper converts the lowercase letter c to the corresponding uppercase letter. 

The character mapping is determined by the LC_CTYPE category of the current 
locale. 

Return Value Both functions return the converted character. If the character c does not have a 
corresponding lowercase of uppercase character, the functions return c unchanged. 

This example uses toupper and tolower to modify characters between code 0 and 
code 7f. 

#include <stdio.h> 
linclude <ctype.h> 

int main(void) 

{ 

int ch; 

/* print hex values of characters */ 
for (ch = 0; ch <= 0x7f; ch++) { 

printf("toupper=%#04x\n", toupper(ch)); 
printf("tolower=%#04x\n", tolower(ch)); 
putchar('\n 1 ); 

} 

return 0; 

} 

• “i sal num to i sxdigi t — Test Integer Value” on page 347 

• “isascii —Test Integer Values” on page 350 

• “_iscsym - _i scsymf — Test Integer” on page 356 

• “_toascii - _tolower - _toupper — Convert Character” on page 673 

• “fowl ower - towupper — Convert Wide Character Case” on page 677 

• “<ctype.h>” on page 802 
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towlower - 

Format 

Description 


Return Value 



towupper — Convert Wide Character Case 

linclude <wctype.h> 
wint_t towlower(wint_t wc); 
wint_t towupper(wint_t wc); 

Language Level: ANSI 93, POSIX 

towl ower converts the uppercase letter wc to the corresponding lowercase letter, 
towupper converts the lowercase letter wc to the corresponding uppercase letter. 
The character mapping is determined by the LC_CTYPE category of current locale. 


Both functions return the converted character. If the wide character wc does not 
have a corresponding lowercase or uppercase character, the functions return wc 
unchanged. 

This example uses towlower and towupper to convert characters between 0 and 0x7f. 

#include <wchar.h> 

#include <stdio.h> 

int main(void) 

{ 

wint_t w_ch; 

for (w_ch = 0; w_ch <= 0x7f; w_ch++) { 

printf ("towupper : %#04x %#04x, ", w_ch, towupper(w_ch)); 
printf ("towlower : %#04x %#04x\n", w_ch, towlower(w_ch)); 

} 

return 0; 

/**************************************************************************** 

The output should be similar to : 


towupper 

0x41 

0x41, 

towlower 

0x41 

0x61 

towupper 

0x42 

0x42, 

towlower 

0x42 

0x62 

towupper 

0x43 

0x43, 

towlower 

0x43 

0x63 

towupper 

0x44 

0x44, 

towlower 

0x44 

0x64 

towupper 

0x45 

0x45, 

towlower 

0x45 

0x65 


towupper 

0x61 

0x41, 

towlower 

0x61 

0x61 

towupper 

0x62 

0x42, 

towlower 

0x62 

0x62 

towupper 

0x63 

0x43, 

towlower 

0x63 

0x63 

towupper 

0x64 

0x44, 

towlower 

0x64 

0x64 

towupper 

0x65 

0x45, 

towl ower 

0x65 

0x65 


**************************************************************************** 

} 


/ 
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“<wctype.h>” on page 823 

“tolower - toupper — Convert Character Case” on page 676 
“_toascii - _tolower - _toupper — Convert Character” on page 673 
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_treal1oc 

Format 

Description 


Return Value 


Reallocate Tiled Storage Block 

linclude <stdlib.h> /* also in <malloc.h> */ 
void _trealloc(void *ptr, size_t size); 

Language Level: Extension 

_treal loc changes the size of the tiled memory pointed to ptr to the specified 
size , in bytes. The contents of the tiled memory are unchanged up to the smaller of 
the new and old sizes. Any new tiled memory that is allocated is uninitialized. 

To use _treal 1 oc, you must compile with the /Gt compiler option. This option 
maps all real 1 oc calls to _treal 1 oc (you can also call _treal 1 oc explicitly). 

Note: The /Gt option maps all calls to regular memory management functions to 
their tiled versions. To prevent a call from being mapped, parenthesize the function 
name. 

_treal 1 oc works just like real 1 oc except that it reallocates tiled memory instead of 
regular memory. Tiled memory will not to cross 64K boundaries, as long as the 
object is less than 64K in size. Objects larger than 64K in size are aligned on 64K 
boundaries, but will also cross 64K boundaries. If you have objects that may be 
accessed by 16-bit code, you should store them in tiled memory. 

Tiled memory from the Visual Age C++ runtime heap is limited to 512 MB per 
process. You can also create your own heaps of tiled memory, which can be larger 
in size. See Memory Management in the Programming Guide for more information. 

_treal 1 oc can only reallocate memory allocated by the _tmal 1 oc, _tcal 1 oc, or 
_treal loc functions. If the memory was not allocated by one of these functions or 
was previously freed, a message appears and the program ends. 

A debug version of this function, _debug_treal loc, is also available. Use the /Tm 
compiler option to map all _treal loc calls to _debug_treal loc. 

_treal loc returns a pointer to the reallocated tiled memory. If not enough storage 
is available or if size is 0, _treal loc returns NULL and the original block does not 
change. 
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This example uses _treal loc to reallocate a block of tiled memory previously 
allocated by _tmal 1 oc. 

Note: You must compile this example with the /Gt option to enable tiled memory. 
#include <stdlib.h> 


int main(void) 

{ 

char *memoryPtr; 

if (NULL == (memoryPtr = mal1oc(100))) { 
puts("Could not allocate tiled memory."); 
exit(EXIT_FAILURE); 

} 

if (NULL == (memoryPtr = realloc(memoryPtr, 1000))) { 
puts("Unable to reallocate tiled memory."); 
exit(EXIT_FAILURE); 

} 

else 

puts("Successfully reallocated 1000 bytes of tiled memory."); 

free(memoryPtr); 

return 0; 


/•k-k-k-k-k-k-k-k-kle-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-klck-k'k-k-k-k 

The output should be similar to: 

Successfully reallocated 1000 bytes of tiled memory. 

-k , k-ki<‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-ki<‘k-k-k-k-k-k‘k-k-k‘k-k-k j 

} 



“_debug_cal loc — Allocate and Initialize Memory” on page 139 

“_debug_treal 1 oc — Reallocate Tiled Memory Block” on page 157 

“_msi ze — Return Number of Bytes Allocated” on page 441 

“real loc — Change Reserved Storage Block Size” on page 484 

“_tcal loc — Reserve Tiled Storage Block” on page 647 

“_tmal loc — Reserve Tiled Storage Block” on page 667 

“_tfree — Free Tiled Storage Block” on page 659 

“Differentiating between Memory Management Functions” on page 28 

“Managing Memory” in the Programming Guide 

“<malloc.h>” on page 810 

“<stdlib.h>” on page 816 
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tzset — Assign Values to Locale Information 

Format linclude <time.h> 

void tzset(void); 

Description Language Level: XPG4, Extension 

tzset uses the environment variable TZ to change the time zone and daylight saving 
time (DST) zone values of your current locale. These values are used by the gmtime 
and local time functions to make corrections from Coordinated Universal Time 
(formerly GMT) to local time. 

To use tzset, set the TZ variable to the appropriate values. (For the possible values 
for TZ, see the chapter on runtime environment variables in the Programming Guide.) 
Then call tzset to incorporate the changes in the time zone information into your 
current locale. 


To set TZ from within a program, use putenv before calling tzset. 

Notes: 

1. In earlier releases of C Set ++, tzset began with an underscore (_tzset). 
Because it is defined by the X/Open standard, the underscore has been removed. 
For compatibility, VisualAge C++ will map _tzset to tzset for you. 

2. The time and date functions begin at 00:00:00 Coordinated Universal Time, 
January 1, 1970. 

Return Value There is no return value. 

This example uses putenv and tzset to set the time zone to Central Time. 

#inc1ude <time.h> 

#include <stdi o.h> 

#inc1ude <stdlib.h> 

int main(void) 

{ 

time_t currentTime; 
struct tm *ts; 
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/* Get the current time */ 

(void)time(&currentTime); 

printf("The GMT time is %s", asctime(gmtime(&currentTime))); 
ts = 1 ocaltime(&currentTime); 

if (ts->tm_isdst > 0) /* check if Daylight Saving Time is in effect */ 

{ 

printf("The local time is %s", asctime(ts)); 
printf("Daylight Saving Time is in effect.\n"); 

} 

else { 

printf("The local time is %s", asctime(ts)); 
printf("Daylight Saving Time is not in effect.\n"); 

} 

printf("**** Changing to Central Time ****\n"); 
putenv("TZ=CST6CDT"); 
tzset(); 

ts = 1 ocal time(&currentTime); 

if (ts->tm_isdst > 0) /* check if Daylight Saving Time is in effect */ 

{ 

printf("The local time is %s", asctime(ts)); 
printf("Daylight Saving Time is in effect.\n"); 

} 

else { 

printf("The local time is %s", asctime(ts)); 
printf("Daylight Saving Time is not in effect.\n"); 

} 


return 0; 

/**************************************************************************** 

The output should be similar to: 

The GMT time is Fri Jan 13 21:49:26 1995 
The local time is Fri Jan 13 16:49:26 1995 
Daylight Saving Time is not in effect. 

**** Changing to Central Time **** 

The local time is Fri Jan 13 15:49:26 1995 
Daylight Saving Time is not in effect. 

****************************************************************************/ 

} 



“asctime — Convert Time to Character String” on page 55 
“_ftime — Store Current Time” on page 285 
“gmtime — Convert Time” on page 321 
“localtime — Convert Time” on page 385 
“mktime — Convert Local Time” on page 438 
“putenv — Modify Environment Variables” on page 471 
“strftime — Convert to Formatted Time” on page 586 
“t i me — Determine Current Time” on page 666 
“<time.h>” on page 819 
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_uaddmem — 

Format 

Description 


Return Value 



Add Memory to a Heap 

linclude <umalloc.h> 

Heap_t _uaddmem(Heap_t heap, void *block, size_t size, int clean); 

Language Level: Extension 

_uaddmem adds a block of memory of size bytes into the specified user heap 
(created with _ucreate). Before calling _uaddmem, you must first get the block from 
the operating system, typically by using an OS/2 API like DosAl 1 ocMem or by 
allocating it statically. (See the Control Program Guide and Reference for details on 
OS/2 APIs for memory management.) 

If the memory block has been initialized to 0, specify _BLOCK_CLEAN for the clean 
parameter. If not, specify !_BLOCK_CLEAN. (This information makes calloc and 
_ucal loc more efficient). 

Note: Memory returned by DosAl 1 ocMem is initialized to 0. 

For fixed-size heaps, you must return all the blocks you added with _uaddmem to the 
system. (For expandable heaps, these blocks are returned by your release^fn when 
you call _udestroy.) 

For more information about creating and using heaps, see “Managing Memory” in the 
Programming Guide. 

Note: For every block of memory you add, a small number of bytes from it are used 
to store internal information. To reduce the total amount of overhead, it is better to 
add a few large blocks of memory than many small blocks. 


_uaddmem returns a pointer to the heap the memory was added to. If the heap 
specified is not valid, _uaddmem returns NULL. 

The following example creates a heap myheap, and then uses _uaddmem to add 
memory to it. 
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#define INCL_DOSMEMMGR /* Memory Manager values */ 

#include <os2.h> 

linclude <bsememf.h> /* Get flags for memory management */ 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 

int main(void) 

{ 

void *initial_block, *extra_chunk; 

API RET rc; 

Heap_t myheap; 
char *pl, *p2; 

/* Call DosAllocMem to get the initial block of memory */ 
if (0 != (rc = DosAl1ocMem(&initial_block, 65536, 

PAG_WRITE | PAG_READ | PAG_COMMIT))) { 
printf("DosAllocMem for initial block failed: return code = %ld\n", rc 
exit(EXIT_FAILURE); 

} 

/* Create a fixed size heap starting with the block declared earlier */ 
if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN, 

_HEAP_REGULAR, NULL, NULL))) { 

puts("_ucreate failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != _uopen(myheap)) { 
puts("_uopen failed."); 
exit(EXIT_FAILURE); 

} 

pi = _umal1oc(myheap, 100); 

/* Call DosAllocMem to get another block of memory */ 
if (0 != (rc = DosAl1ocMem(&extra_chunk, 10 * 65536, 

PAG_WRITE | PAG_READ | PAG_C0MMIT))) { 
printf("DosAllocMem for extra chunk failed: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

/* Add the second chunk of memory to user heap */ 

if (myheap != _uaddmem(myheap, extra_chunk, 10 * 65536, _BLOCK_CLEAN)) { 
puts("_uaddmem failed."); 
exit(EXIT_FAILURE); 

} 

p2 = _umalloc(myheap, 100000); 
free(pl); 
free(p2); 
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if (0 != _uclose(myheap)) { 
puts("_uclose failed"); 
exit(EXIT_FAILURE); 

} 

if (0 != DosFreeMem(initial_block) || 0 != DosFreeMem(extra_chunk)) { 
puts("DosFreeMem error."); 
exit(EXIT_FAILURE); 

} 

return 0; 


• “_ucreate — Create a Memory Heap” on page 690 

• “_udestroy — Destroy a Heap” on page 696 

• “_uheapmin — Release Unused Memory in User Heap” on page 709 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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_ucal1oc — 

Format 

Description 


Return Value 



Reserve and Initialize Memory from User Heap 

#include <umalloc.h> 

void *_ucalloc(Heap_t heap, size_t num, size_t size); 

Language Level: Extension 

_ucal 1 oc allocates memory for an array of num elements, each of length size bytes, 
from the heap you specify. It then initializes all bits of each element to 0. 

_ucal 1 oc works just like cal 1 oc except that you specify the heap to use; cal 1 oc 
always allocates from the default heap. A debug version of this function, 
_debug_ucal loc, is also provided. 

If the heap does not have enough memory for the request, _ucal loc calls the 
getmore^fn that you specified when you created the heap with _ucreate. 

To reallocate or free memory allocated with _ucal loc, use the non-heap-specific 
realloc and free. These functions always check what heap the memory was 
allocated from. 

_ucal 1 oc returns a pointer to the reserved space. If size or num was specified as 
zero, or if your getmore^fn cannot provide enough memory, _ucal loc returns 
NULL. Passing _ucal loc a heap that is not valid results in undefined behavior. 

This example creates a heap myheap and then uses _ucalloc to allocate memory from 
it. 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 

#include <string.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptr = _ucalloc(myheap, 100, 1))) { 
puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x', 10); 
free(ptr); 
return 0; 
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• “cal loc — Reserve and Initialize Storage” on page 80 

• “_debug_ucal 1 oc — Reserve and Initialize Memory from User Heap” on 
page 160 

• “free — Release Storage Blocks” on page 263 

• “real loc — Change Reserved Storage Block Size” on page 484 

• “_ucreate — Create a Memory Heap” on page 690 

• “_umal 1 oc — Reserve Memory Blocks from User Heap” on page 717 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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uclose — Close Heap from Use 

Format #include <umalloc.h> 

int _uclose(Heap_t heap); 

Description Language Level: Extension 

_uclose closes a heap when a process will not use it again. After you close a heap, 
any attempt in the current process to allocate or return memory to it will have 
undefined results. _uclose affects only the current process; if the heap is shared, 
other processes may still be able to access it. 

Once you have closed the heap, use _udestroy to destroy it and return all its 
memory to the operating system. 

Note: If the heap is shared, you must close it in all processes that share it before 
you destroy it, or undefined results will occur. 

You cannot close the VisualAge C++ runtime heap (_RUNTIME_HEAP). 

For more information about creating and using heaps, see “Managing Memory” in the 
Programming Guide. 


Return Value If successful, _uclose returns 0. A nonzero return value indicates failure. Passing 
_uclose a heap that is not valid results in undefined behavior. 



This example creates and opens a heap, and then performs operations on it. It then 
calls _uclose to close the heap before destroying it. 


#defi 

ne 

INCL_DOSMEMMGR 

#i 

ncl 

ude 

<os2.h> 

#i 

ncl 

ude 

<bsememf.h> 

#i 

ncl 

ude 

<stdlib.h> 

#i 

ncl 

ude 

<stdio.h> 

# i 

ncl 

ude 

<umal1oc.h> 


/* Memory Manager values */ 

/* Get flags for memory management */ 
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int main(void) 

{ 

void *initial_block; 

APIRET rc; 

Heap_t myheap; 
char *p; 

/* Call DosAllocMem to get the initial block of memory */ 
if (0 != (rc = DosAl1ocMem(&initial_block, 65536, 

PAG_WRITE | PAG_READ j PAG_COMMIT))) { 
printf("DosAl1ocMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

/* Create a fixed size heap starting with the block declared earlier */ 
if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN, 

_HEAP_REGULAR, NULL, NULL))) { 

puts("_ucreate failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != _uopen(myheap)) { 
puts("_uopen failed."); 
exit(EXIT_FAILURE); 

} 

p = _umalloc(myheap, 100); 
memset(p, 'x', 10); 
free(p); 

if (0 != _uclose(myheap)) { 
puts("_uclose failed"); 
exit(EXIT_FAILURE); 

} 

if (0 != (rc = DosFreeMem(initial_block))) { 

printf("DosFreeMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

return 0; 


• “_uopen — Open Heap for Use” on page 730 

• “_udestroy — Destroy a Heap” on page 696 

• “_ucreate — Create a Memory Heap” on page 690 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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_ucreate - 

Format 

Description 


Create a Memory Heap 

linclude <umalloc.h> 

Heap_t _ucreate(void *block, size_t initsz, int clean, int memtype, 
void * (*getmorej'n ) (Heap_t, size_t *, int *) 
void (*release_fn) (Heap_t, void *, size_t); 


Language Level: Extension 

_ucreate creates your own memory heap that you can allocate and free memory 
from, just like the VisualAge C++ runtime heap. 


Before you call _ucreate, you must first get the initial block of memory for the 
heap. You can get this block by calling an OS/2 API (such as DosAllocMem or or 
DosAl 1 ocSharedMem) or by statically allocating it. (See the CP Programming Guide 
and Reference for more information on the OS/2 APIs.) 

Note: You must also return this initial block of memory to the system after you 
destroy the heap. 


When you call _ucreate, you pass it the following parameters: 


block 

initsz 


clean 


memtype 


The pointer to the initial block you obtained. 

The size of the initial block, which must be at least 
_HEAP_MIN_SIZE bytes (defined in <mal 1 oc.h>). If you are 
creating a fixed-size heap, the size must be large enough to satisfy 
all memory requests your program will make of it. 

The macro _BLOCK_CLEAN, if the memory in the block has been 
initialized to 0, or !_BLOCK_CLEAN, if the memory has not been 
touched. This improves the efficiency of _ucal loc; if the memory 
is already initialized to 0, _ucal loc does not need to initialize it. 

Note: DosAl locMem initializes memory to 0 for you. You can also 
use memset to initialize the memory; however, memset also commits 
all the memory at once, an action that could slow overall 
performance. 

A macro indicating the type of memory in your heap: 
_HEAP_REGULAR (regular) or _HEAP_TILED (tiled). If you 
want the memory to be shared, specify _HEAP_SHARED as well 
(for example, _HEAP_REGULAR | _HEAP_SHARED). Tiled memory blocks 
will not cross 64K boundaries, so the data in them can be used in 
16-bit programs. Shared memory can be shared between different 
processes. For more information on different types of memory, see 
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the Programming Guide and the Control Program Guide and 
Reference. 

Note: Make sure that when you get the initial block, you request 
the same type of memory that you specify for memtype. 

getmore^fn A function you provide to get more memory from the system 
(typically using OS/2 APIs or static allocation). To create a 
fixed-size heap, specify NULL for this parameter. 

release_fn A function you provide to return memory to the system (typically 
using DosFreeMem). To create a fixed-size heap, specify NULL for 
this parameter. 

If you create a fixed-size heap, the initial block of memory must be large enough to 
satisfy all allocation requests made to it. Once the block is fully allocated, further 
allocation requests to the heap will fail. If you create an expandable heap, the 
getmore^fn and release^fn allow your heap to expand and shrink dynamically. 

When you call _umal 1 oc (or a similar function) for your heap, if not enough memory 
is available in the block, it calls the getmore^fn you provide. Your getmore^fn 
then gets more memory from the system and adds it to the heap, using any method 
you choose. 

Your getmore^fn must have the following prototype: 

void *(*getmore_fn)(Heap_t uh, size_t *size, int *clean); 
where: 

uh Is the heap to get memory for. 

size Is the size of the allocation request passed by _umal 1 oc. You probably 
want to return enough memory at a time to satisfy several allocations; 
otherwise, every subsequent allocation has to call getmore^fn. You should 
return multiples of 64K (the smallest size that DosAl 1 ocMem returns). Make 
sure you update the size parameter if you return more than the original 
request. 

clean Within getmorejn , you must set this variable either to _BLOCK_CLEAN, 

to indicate that you initialized the memory to 0, or to !_BLOCK_CLEAN, 
to indicate that the memory is untouched. 

Note: Make sure your getmorejn allocates the right type of memory for the heap. 

When you call _uheapmin to coalesce the heap or _udestroy to destroy it, these 
functions call the release_fn you provide to return the memory to the system, 
function. 
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Return Value 



Your release^fn must have the following prototype: 

void (*release_fn)(Heap_t uh, void *block, size_t size); 

The heap uh the block is from, the block to be returned, and its size are passed to 
release_fn by _uheapmin or _udestroy. 

For more information about creating and using heaps, see the “Managing Memory” in 
the Programming Guide. 


If successful, _ucreate returns a pointer to the heap created. If errors occur, 
_ucreate returns NULL. 

This example uses _ucreate to create an expandable heap. The functions for 
expanding and shrinking the heap are get_fn and release_fn. The program then 
opens the heap and performs operations on it, and then closes and destroys the heap. 

#define INCL_DOSMEMMGR /* Memory Manager values */ 

#include <os2.h> 

linclude <bsememf.h> /* Get flags for memory management */ 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 

static void *get_fn(Heap_t usrheap, size_t *length, int *clean) 

{ 

void *p; 

/* Round up to the next chunk size */ 

*length = ((*1ength) / 65536) * 65536 + 65536; 

*clean = _BLOCK_CLEAN; 

DosAllocMem(&p, *length, PAG_COMMIT | PAG_READ | PAG_WRITE); 
return (p); 


static void release_fn(Heap_t usrheap, void *p, size_t size) 

{ 

DosFreeMem(p); 
return; 
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nt main(void) 

void *initial_block; 

APIRET rc; 

Heap_t myheap; 
char *ptr; 

/* Call DosAl1ocMem to get the initial block of memory */ 
if (0 != (rc = DosAl1ocMem(&initial_block, 65536, 

PAG_WRITE | PAG_READ j PAG_COMMIT))) { 
printf("DosAl1ocMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

/* Create an expandable heap starting with the block declared earlier */ 
if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN, 

_HEAP_REGULAR, get_fn, release_fn))) { 

puts("_ucreate failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != _uopen(myheap)) { 
puts("_uopen failed."); 
exit(EXIT_FAILURE); 

} 


/* Force user heap to grow */ 

ptr = _umal1oc(myheap, 100000); 

_uclose(myheap); 

if (0 != _udestroy(myheap, _F0RCE)) { 
puts("_udestroy failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != (rc = DosFreeMem(initial_block))) { 

printf("DosFreeMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

return 0; 


• “_uaddmem — Add Memory to a Heap” on page 683 

• “_ucal 1 oc — Reserve and Initialize Memory from User Heap” on page 686 

• “_uclose — Close Heap from Use” on page 688 

• “_udestroy — Destroy a Heap” on page 696 

• “_uheapmin — Release Unused Memory in User Heap” on page 709 

• “_umal 1 oc — Reserve Memory Blocks from User Heap” on page 717 

• “_uopen — Open Heap for Use” on page 730 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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udefault — Change the Default Heap 

Format #include <umalloc.h> 

Heap_t _udefault(Heap_t heap); 

Description Language Level: Extension 

_udefaul t makes the heap you specify become the default heap. All calls to 
memory management functions that do not specify a heap (including malloc and 
cal 1 oc) then allocate memory from the heap. 

This change affects only the thread where you called _udefaul t. 

The initial default heap is the VisualAge C++ runtime heap. To restore or explicitly 
set the VisualAge C++ runtime heap as the default, call _udefault with the argument 
_RUNTIME_HEAP. 

You can also use _udefault to find out which heap is being used as the default by 
specifying NULL for the heap parameter. The default heap remains the same. 

For more information about creating and using heaps, see “Managing Memory” in the 
Programming Guide. 


Return Value _udefaul t returns a pointer to the former default heap. You can save this pointer 
and use it later to restore the original heap. If the call is unsuccessful, _udefault 
returns NULL. Passing _udefaul t a heap that is not valid results in undefined 
behavior. 



This example creates a fixed-size heap myheap and uses _udefault to make it the 
default heap. The call to mal loc then allocates memory from myheap. The second 
call to _udefaul t restores the original default heap. 

#define INCL_DOSMEMMGR /* Memory Manager values */ 

#include <os2.h> 

#include <bsememf.h> /* Get flags for memory management */ 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 
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nt main(void) 

void *initial_block; 

API RET rc; 

Heap_t myheap, old_heap; 
char *p; 

/* Call DosAl1ocMem to get the initial block of memory */ 
if (0 != (rc = DosAl 1 ocMem(&initial_block, 65536, 

PAG_WRITE | PAG_READ j PAG_COMMIT))) { 
printf("DosAl1ocMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

/* Create a fixed size heap starting with the block declared earlier */ 
if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN, 

_HEAP_REGULAR, NULL, NULL))) { 

puts("_ucreate failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != _uopen(myheap)) { 
puts("_uopen failed."); 
exit(EXIT_FAILURE); 

} 


/* myheap is used as default heap */ 
old_heap = _udefault(myheap); 

/* malloc will allocate memory from myheap */ 
p = mal1oc(100); 
memset(p, 'x 1 , 10); 

/* Restore original default heap */ 

_udefault(old_heap); 

free(p); 

if (0 != _uclose(myheap)) { 
puts("_uclose failed"); 
exit(EXIT_FAILURE); 

} 

if (0 != (rc = DosFreeMem(initial_block))) { 

printf("DosFreeMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

return 0; 


• “cal loc — Reserve and Initialize Storage” on page 80 

• “mal loc — Reserve Storage Block” on page 403 

• “_mheap — Query Memory Heap for Allocated Object” on page 433 

• “_ucreate — Create a Memory Heap” on page 690 

• “Differentiating between Memory Management Functions” on page 28 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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_udestroy 

Format 

Description 


Return Value 



Destroy a Heap 

linclude <umalloc.h> 

int _udestroy(Heap_t heap, int force); 

Language Level: Extension 

_udestroy destroys the heap you specify. It also returns the heap's memory to the 
system by calling the release^fn you supplied to _ucreate when you created the 
heap. If you did not supply a release^fn, _udestroy simply marks the heap as 
destroyed so no further operations can be performed. You must then return all the 
memory in the heap to the system. 

Note: Whether or not you provide a release^fn, you must always return the initial 
block of memory (that you provided to _ucreate) to the system. 

The force parameter controls the behavior of _udestroy if all allocated objects from 
the heap have not been freed. If you specify _FORCE for this parameter, _udestroy 
destroys the heap regardless of whether allocated objects remain in that process or in 
any other process that shares the heap. If you specify !_FORCE, the heap will not be 
destroyed if any objects are still allocated from it. 

Typically, you call _uclose to close the heap before you destroy it. After you have 
destroyed a heap, any attempt to access it will have undefined results. 

You cannot destroy the VisualAge C++ runtime heap (_RUNTIME_HEAP). 

_udestroy returns 0 whether the heap was destroyed or not. If the heap passed to 
it is not valid, _udestroy returns a nonzero value. 

This example creates and opens a heap, performs operations on it, and then closes it. 
The program then calls _udestroy with the _FORCE parameter to force the 
destruction of the heap. _udestroy calls release_fn to return the memory to the 
system. 
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Idefine INCL_DOSMEMMGR /* Memory Manager values */ 

#include <os2.h> 

linclude <bsememf.h> /* Get flags for memory management */ 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 


static void *get_fn(Heap_t usrheap, size_t *length, int *clean) 

{ 

void *p; 


/* Round up to the next chunk size */ 

*length = ((*length) / 65536) * 65536 + 65536; 

*clean = _BLOCK_CLEAN; 

DosAl1ocMem(&p, *length, PAG_COMMIT | PAG_READ | PAG_WRITE); 
return (p); 


static void release_fn(Heap_t usrheap, void *p, size_t size) 

{ 

DosFreeMem(p); 
return; 


int main(void) 

{ 

void *initial_block; 

APIRET rc; 

Heap_t myheap; 
char *ptr; 

/* Call DosAllocMem to get the initial block of memory */ 
if (0 != (rc = DosAl 1 ocMem(&initial_block, 65536, 

PAG_WRITE | PAG_READ j PAG_COMMIT))) { 
printf("DosAl1ocMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

/* Create an expandable heap starting with the block declared earlier */ 
if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN, 

_HEAP_REGULAR, get_fn, release_fn))) { 

puts("_ucreate failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != _uopen(myheap)) { 
puts("_uopen failed."); 
exit(EXIT_FAILURE); 

} 
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/* Force user heap to grow */ 

ptr = _umal1oc(myheap, 100000); 

_uclose(myheap); 

if (0 != _udestroy(myheap, _F0RCE)) { 
puts("_udestroy failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != (rc = DosFreeMem(initial_block))) { 

printf("DosFreeMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

return 0; 



“_uaddmem — Add Memory to a Heap” on page 683 

“_ucreate — Create a Memory Heap” on page 690 

“_uopen — Open Heap for Use” on page 730 

“_uclose — Close Heap from Use” on page 688 

“Differentiating between Memory Management Functions” on page 28 

“Managing Memory” in the Programming Guide 

“<umalloc.h>” on page 820 
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_udump_allocated — Get Information about Allocated Memory in Heap 

Format linclude <umalloc.h> 

void _udump_allocated(Heap_t heap, int nbytes ); 

Description Language Level: Extension 

For the heap you specify, _udump_al located prints information to stderr about each 
memory block that is currently allocated and was allocated using the debug memory 
management functions (_debug_ucal loc, _debug_umal loc, and so on). 

_udump_al 1 ocated works just like _dump_al 1 ocated, except that you specify the 
heap to use; _dump_allocated always displays information about the default heap. 

Use nbytes to specify how many bytes of each memory block are to be printed. If 
nbytes is: 

Negative value Prints all bytes of each block. 

0 Prints no bytes. 

Positive value Prints the specified number of bytes or the entire block, whichever 
is smaller. 

_udump_al 1 ocated prints the information to stderr by default. You can change the 
destination with the _set_crt_msg_handl e function. 

Call _udump_al 1 ocated at points in your code where you want a report of the 
currently allocated memory. For example, a good place to call _udump_al located is 
a point where most of the memory is already freed and you want to find a memory 
leak, such as at the end of a program. 

You can also use _udump_al 1 ocated_del ta to display information about only the 
memory that was allocated since the previous call to _udump_al 1 ocated or 
_udump_al1ocated_delta. 

To use _udump_al located and the debug versions of the memory management 
functions, specify the debug memory (/Tm) compiler option. 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 
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Return Value There is no return value. Passing _udump_al located a heap that is not valid 
results in undefined behavior. 

This example creates a heap, performs some operations on it, and then calls 
_udump_al 1 ocated to print out information about the allocated memory blocks. 

Note: You must compile this example with the /Tm option to enable the debug 
memory management functions. 

linclude <stdlib.h> 
linclude <stdio.h> 
linclude <umal1 oc.h> 
linclude <string.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptr = _umalloc(myheap, 10))) { 

puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'a', 5); 

_udump_al1ocated(myheap, 10); 

free(ptr); 
return 0; 

/**************************************************************************** 

The output should be similar to : 



START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address; 0x00073890 Size: OxOOOOOOOA (10) 

This memory block was (re)al1ocated at line number 14 in _udump_al1oc.c. 
Memory contents: 61616161 61AAAAAA AAAA [aaaaaeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


■k'k-k-k'k'k-kicic-kicii-k-kii-k-k-k-k-k-k-kic'kic-kic-k-k'k-kicic-k'k'k-k-kic-k-k-k-k-k-k-k'k'k-k-kic-k-kickick-k-kick-kic-k-k-kick-k-kickickic-k 

) 


/ 



“_debug_ucal loc — Reserve and Initialize Memory from User Heap” on 
page 160 

“_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 
“_debug_real loc — Reallocate Memory Block” on page 147 
“_debug_free — Release Memory” on page 141 

“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
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“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_set_crt_msg_handl e — Change Runtime Message Output Destination” on 
page 526 

“_tdump_al located — Get Information about Allocated Tiled Memory” on 
page 649 

“_udump_al 1 ocated_del ta — Get Information about Allocated Memory in 
Heap” on page 702 

“Differentiating between Memory Management Functions” on page 28 
“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“<umalloc.h>” on page 820 
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udump allocated delta — Get Information about Allocated Memory in 
Heap 

Format linclude <umalloc.h> 

void _udump_allocated_delta(Heap_t heap, int nbytes); 

Description Language Level: Extension 

For the heap you specify, _udump_al 1 ocated_del ta prints information to stderr 
about each memory block allocated by a debug memory management function 
(_debug_umal 1 oc and so on) since the last call to _udump_al 1 ocated_del ta or 
_udump_al 1 ocated. 

_udump_al 1 ocated_del ta and _udump_al 1 ocated print the same type of information 
to stderr, but _udump_al located displays information about all blocks that have 
been allocated since the start of your program. 

_udump_al 1 ocated_del ta works just like _dump_al 1 ocated_del ta, except that you 
specify the heap to use; _dump_al 1 ocated_del ta always displays information about 
the default heap. 

Use nbytes to specify how many bytes of each memory block are to be printed. If 
nbytes is: 

Negative value Prints all bytes of each block. 

0 Prints no bytes. 

Positive value Prints the specified number of bytes or the entire block, whichever 
is smaller. 

_udump_al 1 ocated_del ta prints the information to stderr by default. You can 
change the destination with the _set_crt_msg_handl e function. 

To use _udump_al 1 ocated_del ta and the debug versions of the memory 
management functions, specify the debug memory (/Tm) compiler option. 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Return Value There is no return value. Passing _udump_al 1 ocated_del ta a heap that is not 
valid results in undefined behavior. 
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This example creates a heap and allocates memory from it. It then calls 
_udump_al located to display information about the allocated memory. After 
performing more memory operations, it calls _udump_al 1 ocated_del ta to display 
information about the memory allocated since the call to _udump_al located 

Note: You must compile this example with the /Tm option to enable the debug 
memory management functions. 

#include <stdlib.h> 

#include <stdio.h> 

#inc1ude <string.h> 

#include <umal1oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptrl, *ptr2; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptrl = _umalloc(myheap, 10))) { 

puts("Cannot allocate first memory block from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptrl, 'a', 5); 

_udump_allocated(myheap, 10); 

if (NULL == (ptr2 = _umalloc(myheap, 20))) { 

puts("Cannot allocate second memory block from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptr2, 1 b', 5); 

printf("\nResults of _udump_allocated_delta are:\n"); 

_udump_allocated_delta(myheap, 10); 

free(ptrl); 
free(ptr2); 
return 0; 

/**************************************************************************** 

The output should be similar to : 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: 0x00073890 Size: 0xOOOO0O0A (10) 

This memory block was (re)allocated at line number 14 in _udump_alloc_d.c. 
Memory contents: 61616161 61AAAAAA AAAA [aaaaaeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 
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Results of _udump_al1ocated_delta are: 


START OF DUMP OF ALLOCATED MEMORY BLOCKS 


Address: Ox00O738D0 Size: 0x00000014 (20) 

This memory block was (re)allocated at line number 21 in _udump_alloc_d.c. 
Memory contents: 62626262 62AAAAAA AAAA [bbbbbeeeee ] 


END OF DUMP OF ALLOCATED MEMORY BLOCKS 


} 


/ 



“_dump_al 1 ocated — Get Information about Allocated Memory” on page 180 
“_dump_al 1 ocated_del ta — Get Information about Allocated Memory” on 
page 183 

“_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 
“_debug_ucal loc — Reserve and Initialize Memory from User Heap” on 
page 160 

“_debug_real 1 oc — Reallocate Memory Block” on page 147 
“_ se t_crt_msg_handl e — Change Runtime Message Output Destination” on 
page 526 

“_tdump_al 1 ocated_del ta — Get Information about Allocated Tiled Memory” 
on page 652 

“_udump_al located — Get Information about Allocated Memory in Heap” on 
page 699 

“Differentiating between Memory Management Functions” on page 28 
“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“<umalloc.h>” on page 820 
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uheap check — Validate User Memory Heap 

Format linclude <umalloc.h> 

void _uheap_check(Heap_t heap); 

Description Language Level: Extension 

_uheap_check checks all memory blocks in the heap you specify that have been 
allocated or freed using the heap-specific debug versions of the memory management 
functions (_debug_ucal loc, _debug_umal loc, and so on). _uheap_check checks 
that your program has not overwritten freed memory blocks or memory outside the 
bounds of allocated blocks. 

_uheap_check works just like _heap_check, except that you specify the heap to 
check; _heap_check always checks the default heap. 

When you call a heap-specific debug memory management function (such as 
_debug_umal loc), it calls _uheap_check automatically. You can also call 
_uheap_check explicitly. Place calls to _uheap_check throughout your code, 
especially in areas that you suspect have memory problems. 

Calling _uheap_check frequently (explicitly or through the tiled debug memory 
functions) can increase your program's memory requirements and decrease its 
execution speed. To reduce the overhead of heap-checking, you can use the 
DDE4_HEAP_SKIP environment variable to control how often the functions check 
the heap. For example: 

SET DDE4_HEAP_SKIP= 10 

specifies that every tenth call to any debug memory function (regardless of the type 
or heap) checks the heap. Explicit calls to _uheap_check are always performed. For 
more details on DDE4_HEAP_SKIP, see “Skipping Heap Checks” in the 
Programming Guide. 

To use _uheap_check and the debug versions of the memory management functions, 
specify the debug memory (/Tm) compiler option. 

Note: The /Tm option maps all calls to memory management functions (including 
tiled and heap-specific versions) to their debug counterparts. To prevent a call from 
being mapped, parenthesize the function name. 

Return Value There is no return value. 
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This example creates a heap and allocates memory from it. It then calls 
_uheap_check to check the the memory in the heap. 

Note: You must compile this example with the /Tm option to map the _ucal 1 oc 
calls to _debug_ucal 1 oc. 


#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL =* (ptr = _ucal1oc(myheap, 100, 1))) { 
puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'x 1 , 105); /* overwrite storage that was not allocated */ 

_uheap_check(myheap); 

free(ptr); 
return 0; 

/**************************************************************************** 

The output should be similar to ; 

End of allocated object 0x00073890 was overwritten at 0xQ00738f4. 

The first eight bytes of the memory block (in hex) are: 7878787878787878. 
This memory block was (re)al1ocated at line number 13 in _uheap_check.c. 
Heap state was valid at line 13 of _uheap_check.c. 

Memory error detected at line 19 of _uheap_check.c. 
****************************************************************************/ 

} 



“_heap_check — Validate Default Memory Heap” on page 323 
“_debug_ucal loc — Reserve and Initialize Memory from User Heap” on 
page 160 

“_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 

“_debug_real 1 oc — Reallocate Memory Block” on page 147 

“_debug_free — Release Memory” on page 141 

“_uheapchk — Validate Memory Heap” on page 707 

“_uheapset — Validate and Set Memory Heap” on page 711 

“_uheap_wal k — Return Information about Memory Heap” on page 713 

“Managing Memory” in the Programming Guide 

“Debugging Your Heaps” in the Programming Guide 

“<umalloc.h>” on page 820 
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_uheapchk 

Format 

Description 


Return Value 



Validate Memory Heap 

linclude <umalloc.h> 

int _uheapchk(Heap_t heap); 

Language Level: Extension 

_uheapchk checks the heap you specify for minimal consistency by checking all 
allocated and freed objects on the heap. 

_uheapchk works just like _heapchk, except that you specify the heap to check; 
_heapchk always checks the default heap. 

Note: Using the _uheapchk, _uheapset, and _uheap_wal k functions (and their 
equivalents for the default heap) may add overhead to each object allocated from the 
heap. 

_uheapchk returns one of the following values, defined in both <umalloc.h> and 
<mal loc.h>: 

_HEAPBADBEGIN The heap specifed is not valid. It may have been closed or 
destroyed. 

_HEAPBADNODE A memory node is corrupted, or the heap is damaged. 
_HEAPEMPTY The heap has not been initialized. 

_HEAPOK The heap appears to be consistent. 

This example creates a heap and performs memory operations on it. It then calls 
_uheapchk to validate the heap. 

#include <stdlib.h> 

#inc1ude <stdio.h> 

#include <umal1oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 
int rc; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 
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if (NULL == (ptr = _ucal1oc(myheap, 100, 1))) { 
puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

*(ptr - 1) = 'x 1 ; /* overwrite storage that was not allocated */ 

if (_HEAP0K != (rc = _uheapchk(myheap))) { 
switch(rc) { 

case _HEAPEMPTY: 

puts("The heap has not been initialized."); 
break; 

case _HEAPBADNODE; 

puts("A memory node is corrupted or the heap is damaged."); 
break; 

case _HEAPBADBEGIN: 

puts("The heap specified is not valid."); 
break; 

} 

exit(rc); 

} 

free(ptr); 
return 0; 

/•k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k'k-k-kic-k-k‘k-k-k‘k-k-k-k 

The output should be similar to : 

A memory node is corrupted or the heap is damaged. 

-k , k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k‘k-k-k-k-k-k / 

} 



“_heapchk — Validate Default Memory Heap” on page 325 
“_heapmin — Release Unused Memory from Default Heap” on page 327 
“_uheapset — Validate and Set Memory Heap” on page 711 
“_uheap_wal k — Return Information about Memory Heap” on page 713 
“Managing Memory” in the Programming Guide 
“Debugging Your Heaps” in the Programming Guide 
“<umalloc.h>” on page 820 
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_uheapmin 

Format 

Description 


Return Value 



Release Unused Memory in User Heap 

find ude <umalloc.h> 

int _uheapmin(Heap_t heap); 

Language Level: Extension 

_uheapmin returns all unused memory blocks from the heap you specify to the 
operating system. 

_uheapmin works just like _heapmin, except that you specify the heap to use; 
_heapmi n always uses the default heap. A debug version of this function, 
_debug_uheapmin, is also provided. 

To return the memory, _uheapmin calls the release_fn you supplied when you 
created the heap with _ucreate. If you did not supply a release^fn, _uheapmin 
has no effect and simply returns 0. 

If successful, _uheapmi n returns 0. A nonzero return value indicates failure. 
Passing _uheapmi n a heap that is not valid has undefined results. 

This example creates a heap and then allocates and frees a large block of memory 
from it. It then calls _uheapmin to return free blocks of memory to the system. 

#include <stdlib.h> 

#include <stdio.h> 
linclude <umal1oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

/* Allocate a large object */ 
if (NULL == (ptr = _umalloc(myheap, 60000))) { 
puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 
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memset(ptr, 'x 1 , 60000); 
free(ptr); 

/* _uheapmin will attempt to return the freed object to the system */ 
if (0 != _uheapmin(myheap)) { 
puts("_uheapmin failed."); 
exit(EXIT_FAILURE); 

} 

return 0; 



“_heapmin — Release Unused Memory from Default Heap” on page 327 

“_debug_uheapmin — Release Unused Memory in User Heap” on page 162 

“_theapmin — Release Unused Tiled Memory” on page 663 

“_ucreate — Create a Memory Heap” on page 690 

“Differentiating between Memory Management Functions” on page 28 

“Managing Memory” in the Programming Guide 

“Debugging Your Heaps” in the Programming Guide 

“<umalloc.h>” on page 820 
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_uheapset 

Format 

Description 


Return Value 



Validate and Set Memory Heap 

linclude <umalloc.h> 

int _heapset(Heap_t heap, unsigned int fill); 

Language Level: Extension 

_uheapset checks the heap you specify for minimal consistency by checking all 
allocated and freed objects on the heap (similar to _uheapchk). It then sets each byte 
of the heap's free objects to the value of fill. 

Using _uheapset can help you locate problems where your program continues to use 
a freed pointer to an object. After you set the free heap to a specific value, when 
your program tries to interpret the set values in the freed object as data, unexpected 
results occur, indicating a problem. 

_uheapset works just like _heapset, except that you specify the heap to check; 
_heapset always checks the default heap. 

Note: Using the _uheapchk, _uheapset, and _uheap_wal k functions (and their 
equivalents for the default heap) may add overhead to each object allocated from the 
heap. 

_uheapset returns one of the following values, defined in both <umalloc.h> and 
<mal loc.h>: 

_HEAPBADBEGIN The heap specified is not valid. It may have been closed or 
destroyed. 

_HEAPBADNODE A memory node is corrupted, or the heap is damaged. 
_HEAPEMPTY The heap has not been initialized. 

_HEAPOK The heap appears to be consistent. 

This example creates a heap and allocates and frees memory from it. It then calls 
_uheapset to set the freed memory to a value. 
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#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

int rc; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptr = _umal1oc(myheap, 100))) { 

puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

memset(ptr, 'A 1 , 10); 
free(ptr); 

if (_HEAP0K != (rc = _uheapset(myheap, 'x'))) { 
switch(rc) { 

case _HEAPEMPTY: 

puts("The heap has not been initialized."); 
break; 

case _HEAPBADN0DE: 

puts("A memory node is corrupted or the heap is damaged."); 
break; 

case _HEAPBADBEGIN: 

puts("The heap specified is not valid."); 
break; 

} 

exit(rc); 

} 

return 0; 

} 



“_heapmin — Release Unused Memory from Default Heap” on page 327 

“_heapset — Validate and Set Default Heap” on page 328 

“_uheapchk — Validate Memory Heap” on page 707 

“_uheap_wal k — Return Information about Memory Heap” on page 713 

“Managing Memory” in the Programming Guide 

“Debugging Your Heaps” in the Programming Guide 

“<umalloc.h>” on page 820 
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uheap wal k — Return Information about Memory Heap 

linclude <umalloc.h> 

int _uheap_walk(Heap_t heap, int (*callback_fn )(const void * object, 
size_t size, int flag, int status, 
const char* file, int line ) ); 

Description Language Level: Extension 

_uheap_wal k traverses the heap you specify, and, for each allocated or freed object, 
it calls the callback^fn function that you provide. _uheap_wal k works just like 
_heap_wal k, except that you specify the heap to be traversed; _heap_wal k always 
traverses the default heap. 

For each object, _uheap_wal k passes your function: 

object A pointer to the object. 
size The size of the object. 

flag The value _USEDENTRY, if the object is currently allocated, or 

_FREEENTRY, if the object has been freed. (Both values are defined in 
<mal loc.h>.) 

status One of the following values, defined in both <umalloc.h> and <malloc.h>, 
depending on the status of the object; 

_HEAPBADBEGIN The heap specified is not valid. It may have been 
closed or destroyed. 

_HEAPBADNODE A memory node is corrupted, or the heap is 
damaged. 

_HEAPEMPTY The heap has not been initialized. 

_HEAPOK The heap appears to be consistent. 

fi le The name of the file where the object was allocated or freed. 

line The line where the object was allocated or freed. 

_uheap_wal k provides information about all objects, regardless of which memory 
management functions were used to allocate them. However, the fi le and l ine 
information are only available if the object was allocated and freed using the debug 
versions of the memory management functions. Otherwise, file is NULL and l ine 
is 0. 

_uheap_wal k calls cal Iback^fn for each object until one of the following occurs: 

• All objects have been traversed. 

• callback^fn returns a nonzero value to _heap_wal k. 

• It cannot continue because of a problem with the heap. 

You may want to code your cal lback_fn to return a nonzero value if the status of 
the object is not _HEAPOK. Even if cal lback_fn returns 0 for an object that is 
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corrupted, _heap_wal k cannot continue because of the state of the heap and returns to 
its caller. 

You can use cal Iback^fn to process information from _uheap_wal k in various ways. 
For example, you may want to print the information to a file, or use it to generate 
your own error messages. You can use the information to look for memory leaks and 
objects incorrectly allocated or freed from the heap. It can be especially useful to call 
_uheap_wal k when _uheapchk returns an error. 

Notes: 

1. Using the _uheapchk, _uheapset, and _uheap_wal k functions (and their 
equivalents for the default heap) may add overhead to each object allocated from 
the heap 

2. _uheap_wal k locks the heap while it traverses it, to ensure that no other 
operations use the heap until _uheap_wal k finishes. As a result, in your 

cal lback_fn, you cannot call any critical functions in the runtime library, either 
explicitly or by calling another function that calls a critical function. See the 
Programming Guide for a list of critical functions. 


Return Value _uheap_wal k returns the last value of status to the caller. 



This example creates a heap and performs memory operations on it. _uheap_wal k 
then traverses the heap and calls cal 1 back_functi on for each memory object. The 
cal 1 back_function prints a message about each memory block. 


#include <stdlib.h> 
linclude <stdio.h> 

#include <umal1oc.h> 


int cal 1back_function(const void *pentry, size_t sz, int useflag, int status, 
const char *filename, size_t line) 


{ 


if (_HEAP0K != status) { 


puts("status is not _HEAP0K."); 
exit(status); 


if (_USEDENTRY == useflag) 

printf("allocated %p %u\n", pentry, sz); 

else 

printf("freed %p %u\n", pentry, sz); 

return 0; 
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int main(void) 

{ 

Heap_t myheap; 
char *pl, *p2, *p3; 

/* User default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (pi = _umal 1 oc(myheap, 100)) 

NULL == (p2 = _umal 1 oc(myheap, 200)) 

NULL == (p3 = _umal 1 oc(myheap, 300))) { 
puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

free(p2); 

puts("usage address size\n- - -"); 

_uheap_walk(myheap, cal 1back_function); 

free(pl); 
free(p3); 
return 0; 

/**************************************************************************** 


The output 

should be 

simi 

usage 

address 

size 

al1ocated 

73A20 

300 

al1ocated 

738C0 

100 

freed 

73930 

224 


****************************************************************************/ 


• “_heapmin — Release Unused Memory from Default Heap” on page 327 

• “_heap_wal k — Return Information about Default Heap” on page 330 

• “_uheapchk — Validate Memory Heap” on page 707 

• “_uheapset — Validate and Set Memory Heap” on page 711 

• “Managing Memory” in the Programming Guide 

• “Debugging Your Heaps” in the Programming Guide 

• “<umalloc.h>” on page 820 
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ultoa — Convert Unsigned Long Integer to String 

Format linclude <stdlib.h> 

char *_ultoa(unsigned long value, char *string, int radix); 

Description Language Level: Extension 

_ultoa converts the digits of the given unsigned long value to a null-terminated 
character string and stores the result in string. No overflow checking is performed. 
The radix argument specifies the base of value ; it must be in the range of 2 through 
36. 

The space allocated for string must be large enough to hold the returned string. The 
function can return up to 33 bytes, including the null character (\0). 

Return Value _ultoa returns a pointer to string. There is no error return value. 

This example converts the digits of the value 255 to decimal, binary, and hexadecimal 
representations. 

linclude <stdio.h> 
linclude <stdlib.h> 

int main(void) 

{ 

char buffer[10]; 
char *p; 

p = _ultoa(255UL, buffer, 10); 

printf("The result of _ultoa(255) with radix of 10 is %s\n", p); 
p = _ultoa(255UL, buffer, 2); 

printf("The result of _ultoa(255) with radix of 2 is %s\n", p); 
p = _ultoa(255UL, buffer, 16); 

printf("The result of _ultoa(255) with radix of 16 is %s\n", p); 
return 0; 

I ■k-k-kle-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'kklt'k-kic-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k'k-k'k-k-k-k-k-k'k-k-k'k 

The output should be: 

The result of _ultoa(255) with radix of 10 is 255 
The result of _ultoa(255) with radix of 2 is 11111111 

The result of _ultoa(255) with radix of 16 is ff 

■k-k-k-klt-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kit/ 

} 

• “_ecvt — Convert Floating-Point to Character” on page 192 

• “_fcvt — Convert Floating-Point to String” on page 217 

• “_gcvt — Convert Floating-Point to String” on page 294 

• “_i toa — Convert Integer to String” on page 368 

• “_1 toa — Convert Long Integer to String” on page 395 

• “<stdlib.h>” on page 816 




716 VisualAge C++ C Library Reference 




umalloe 


umal loc — Reserve Memory Blocks from User Heap 

Format linclude <umalloc.h> 

void *_umalloc(Heap_t heap, size_t size); 

Description Language Level: Extension 

_umal loc allocates a memory block of size bytes from the heap you specify. 

Unlike _ucal 1 oc, _umal 1 oc does not initialize all bits to 0. 

_umal 1 oc works just like mal 1 oc, except that you specify the heap to use; mal 1 oc 
always allocates from the default heap. A debug version of this function, 

_debug_umal loc, is also provided. 

If the heap does not have enough memory for the request, _umal loc calls the 
getmore^fn that you specified when you created the heap with _ucreate. 

To reallocate or free memory allocated with _umal 1 oc, use the non-heap-specific 
realloc and free. These functions always check what heap the memory was 
allocated from. 

Return Value _umal loc returns a pointer to the reserved space. If size was specified as 0, or if 

your getmore^fn cannot provide enough memory, _umalloc returns NULL. Passing 
_umal 1 oc a heap that is not valid results in undefined behavior. 

This example creates a heap and uses _umal 1 oc to allocate memory from the heap. 

#include <stdlib.h> 

#inc1ude <stdio.h> 

#inc1ude <umal1oc.h> 

int main(void) 

{ 

Heap_t myheap; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 

if (NULL == (ptr = _umalloc(myheap, 100))) { 

puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

free(ptr); 
return 0; 

1 

• “cal loc — Reserve and Initialize Storage” on page 80 

• “_debug_umal 1 oc — Reserve Memory Blocks from User Heap” on page 164 

• “free — Release Storage Blocks” on page 263 
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• “mal loc — Reserve Storage Block” on page 403 

• “real loc — Change Reserved Storage Block Size” on page 484 

• “_ucal loc — Reserve and Initialize Memory from User Heap” on page 686 

• “_ucreate — Create a Memory Heap” on page 690 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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umask — Sets File Mask of Current Process 

Format linclude <io.h> 

linclude <sys\stat.h> 
int umask(int pmode); 

Description Language Level: XPG4, Extension 

umask sets the file permission mask of the environment for the currently running 
process to the mode specified by pmode. The file permission mask modifies the 
permission setting of new files created by creat, open, or _sopen. 

If a bit in the mask is 1, the corresponding bit in the requested permission value of 
the file is set to 0 (disallowed). If a bit in the mask is 0, the corresponding bit is left 
unchanged. The permission setting for a new file is not set until the file is closed for 
the first time. 

The possible values for pmode are defined in <sys\stat.h>: 

Value Meaning 

S_IREAD No effect 

SJWRITE Writing not permitted 

S_IREAD I S_IWRITE Writing not permitted. 

If the write bit is set in the mask, any new files will be read-only. You cannot give 
write-only permission, meaning that setting the read bit has no effect. 

Note: In earlier releases of C Set ++, umask began with an underscore (_umask). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _umask to umask for you. 

Return Value umask returns the previous value of pmode. A return value of -1 indicates that the 
value used for pmode was not valid, and errno is set to EINVAL. 
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This example sets the permission mask to create a write-only file. 

linclude <sys\stat.h> 
linclude <io.h> 
linclude <stdio.h> 


int main(void) 



int oldMask; 

oldMask = umask(S_IWRITE); 

printf("\nDefault system startup mask is %d.\n", oldMask); 
return 0; 

/icic*ic1cic*iti(ici(itic-k-k-k-k-k-k-ki(-k-k-ki(-k-k-k-k-k-k-ki(ic-k-k-k-k-k-k-k-k-k-ki(-k-k-ki(-k-k-k‘k-k-k-ki(-k-k-ki(-k-k-k-k-k-k-k-k-k-k-ki(-k-k-k 

The output should be: 

Default system startup mask is 0. 

icicic^-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k'k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k/ 

1 

• “chmod — Change File Permission Setting” on page 90 

• “creat — Create New File” on page 115 

• “open — Open File” on page 447 

• “_sopen — Open Shared File” on page 545 

• “<io.h>” on page 804 

• “<sys\stat.h>” on page 819 
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ungetc — Push Character onto Input Stream 

Format linclude <stdio.h> 

int ungetc(int c, FILE *stream); 

Description Language Level: ANSI, SAA, POSIX, XPG4 

ungetc pushes the unsigned character c back onto the given input stream. However, 
only one sequential character is guaranteed to be pushed back onto the input stream if 
you call ungetc consecutively. The stream must be open for reading. A subsequent 
read operation on the stream starts with c. The character c cannot be the EOF 
character. 

Characters placed on the stream by ungetc will be erased if fseek, fsetpos, rewi nd, 
or fflush is called before the character is read from the stream. 


Return Value ungetc returns the integer argument c converted to an unsigned char, or EOF if c 
cannot be pushed back. 



In this example, the while statement reads decimal digits from an input data stream 
by using arithmetic statements to composethe numeric values of the numbers as it 
reads them. When a nondigit character appears before the end of the file, ungetc 
replaces it in the input stream so that later input functions can process it. 

#include <stdio.h> 

#inc1ude <ctype.h> 


int main(void) 

{ 

int ch; 

unsigned int result = 0; 


while (EOF != (ch = getc(stdin)) && isdigit(ch)) 
result = result * 10 + ch -'0'; 
if (EOF != ch) 

/* Push back the nondigit character onto the input stream */ 

ungetc(ch, stdin); 


printf("Input number : %d\n", result); 
return 0; 


/**************************************************************************** 
For the following input: 


12345s 


The output should be: 


Input number : 12345 


****************************************************************************/ 
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“getc - getchar — Read a Character” on page 296 
“ffl ush — Write Buffer to File” on page 224 
“fseek — Reposition File Position” on page 273 
“fsetpos — Set File Position” on page 275 
“putc - putchar — Write a Character” on page 468 
“rewi nd — Adjust Current File Position” on page 497 
“_ungetch — Push Character Back to Keyboard” on page 723 
“<stdio.h>” on page 815 
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_ungetch — 

Format 

Description 

Return Value 



Push Character Back to Keyboard 

linclude <conio.h> 
int _ungetch(int c); 

Language Level: Extension 

_ungetch pushes the character c back to the keyboard, causing c to be the next 
character read. _ungetch fails if called more than once before the next read 
operation. The character c cannot be the EOF character. 


If successful, _ungetch returns the character c. A return value of EOF indicates an 
error. 

This example uses _getch to read a string delimited by the character 'x'. It then 
calls _ungetch to return the delimiter to the keyboard buffer. Other input routines 
can then process the delimiter. 

linclude <conio.h> 
linclude <stdio.h> 

int main(void) 

{ 

int ch; 

printf("Type in some letters.\n"); 
printf("If you type in an 'x 1 , the program ends.\n"); 
for (; ; ) { 
ch = _getch(); 
if ('x 1 == ch) { 

_ungetch(ch); 
break; 

} 

_putch(ch); 

} 

ch = _getch(); 

printf("\nThe last character was '%c'.", ch); 
return 0; 
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^-k-k^k-k-k-k-k-k-k-k^k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k^k-k-k-k-k-k-k-k^k-k-k-k^k-k-k-k^k-k 

Here is the output from a sample run: 

Type in some letters. 

If you type in an 'x 1 , the program ends. 

One Two Three Four Five Si 
The last character was 'x 1 . 

-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k^k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k^k-k-k-k-k-k-k-k-k-k-k-k-k/ 

} 
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• “_cscanf — Read Data from Keyboard” on page 127 

• “_getch - _getche — Read Character from Keyboard” on page 298 

• “_putch — Write Character to Screen” on page 470 

• “ungetc — Push Character onto Input Stream” on page 721 

• “<conio.h>” on page 802 
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ungetwc — Push Wide Character onto Input Stream 

Format linclude <stdio.h> 

linclude <wchar.h> 

wint_t ungetwc(wint_t wc, FILE *stream ); 

Description Language Level: XPG4 

ungetwc pushes the wide character by wc back onto the input stream. The 
pushed-back wide characters will be returned by subsequent reads on that stream in 
the reverse order of their pushing. A successful intervening call (on the stream) to a 
file positioning function (fseek, fsetpos, or rewind) discards any pushed-back wide 
characters for the stream. 

The external storage corresponding to the stream is unchanged. There is always at 
least one wide character of push-back. 

If the value of wc is WEOF, the operation fails and the input stream is unchanged. 

A successful call to the ungetwc function clears the EOF indicator for the stream. 

The value of the file position indicator for the stream after reading or discarding all 
pushed-back wide characters is the same as it was before the wide characters were 
pushed back. 

For a text stream, the file position indicator is backed up by one wide character. This 
affects ftel 1, fflush, fseek (with SEEK_CUR), and fgetpos. 

For a binary stream, the position indicator is unspecified until all characters are read 
or discarded, unless the last character is pushed back, in which case the file position 
indicator is backed up by one wide character. This affects ftel 1, fseek (with 
SEEK_CUR), fgetpos, and fflush. 

After calling ungetwc, flush the buffer or reposition the stream pointer before calling 
a read function for the stream, unless EOF has been reached. After a read operation 
on the stream, flush the buffer or reposition the stream pointer before calling 
ungetwc. 

Notes: 

1. Under VisualAge C++, only 1 wide character may be pushed back. 

2. The position on the stream after a successful call to ungetwc is one wide 
character prior to the current position. 
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Return Value 



ungetwc returns the wide character pushed back after conversion, or WEOF if the 
operation fails. 

This example reads in wide characters from stream, and then calls ungetwc to push 
the characters back to the stream. 

#include <wchar.h> 

#inc1ude <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

FILE *stream; 

wint_t wc; 

wint_t wc2; 

unsigned int result = 0; 

if (NULL == (stream = fopen("ungetwc.dat", "r+"))) { 
printf("Unable to open fi1e.\n"); 
exit(EXIT_FAILURE); 

} 


while (WEOF != (wc = fgetwc(stream)) && iswdigit(wc)) 
result = result * 10 + wc - L'0'; 

if (WEOF != wc) 

ungetwc(wc, stream); /* Push the nondigit wide character back */ 

/* get the pushed back character */ 
if (WEOF != (wc2 = fgetwc(stream))) { 
if (wc != wc2) { 

printf("Subsequent fgetwc does not get the pushed back character.\n"); 
exit(EXITFAILURE); 

} 

printf("The digits read are 1 %i 1 \n" 

"The character being pushed back is '%lc'", result, wc2); 


return 0; 

/**************************************************************************** 
Assuming the file ungetwc.dat contains: 

12345ABCDE67890XYZ 

The output should be similar to : 

The digits read are '12345' 

The character being pushed back is 'A' 

****************************************************************************/ 

} 


ffl ush — Write Buffer to File” on page 224 
fseek — Reposition File Position” on page 273 
fsetpos — Set File Position” on page 275 
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• “getwc — Read Wide Character from Stream” on page 315 

• “putwc — Write Wide Character” on page 474 

• “ungetc — Push Character onto Input Stream” on page 721 

• “_ungetch — Push Character Back to Keyboard” on page 723 

• “<wchar.h>” on page 821 
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unlink — Delete File 


Format linclude <stdio.h> /* also in <io.h> */ 

int unlink(const char *pathname); 


Description Language Level: XPG4, Extension 

uni ink deletes the file specified by pathname. 

Portability Note: For portability, use the ANSI/ISO function remove, instead of 
uni ink. 

Note: In earlier releases of C Set ++, uni ink began with an underscore (_unlink). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _unlink to uni ink for you. 


Return Value uni ink returns 0 if the file is successfully deleted. A return value of -1 indicates an 
error, and errno is set to one of the following values: 


Value 

EACCESS 

EISOPEN 

ENOENT 


Meaning 

The path name specifies a read-only file or a directory. 

The file is open. 

An incorrect path name was specified, or the file or path name was 
not found. 



This example deletes the file tmpfi 1 e from the system or prints an error message if 
unable to delete it. 

linclude <stdio.h> 


int main(void) 


if (-1 == uniink("tmpfi 1 e")) 

perror("Cannot delete tmpfile"); 
el se 

printf("tmpfile has been successfully deleted\n"); 
return 0; 



/i(ici(ici(-k*i<i(icicicicic*1ci(icic-kicicicic'k-k-k-k-k-k-k-ki(-k-k-k , k-k-k-ki(-k-k-kic-k-k-k'k-k-k-k-k-k-k-ki(-k-k-k‘k-k-k-ki(-k-k-k-k-k-k-k-k-k-k-k 

If the file "tmpfile" exists, the output should be: 
tmpfile has been successfully deleted 

itieicici<i(-k*itic-k*iticic-k-ki(-k-k-ki(-k-k-k-k-k-k-ki(-k-k-k-k-k-k-k , k-k-k-kic-k-k-ki(-k-k-k-k-k-k-ki(-k-k-k-k-k-k-k-kic-k-k-k-k-k-kic-k-k-ki(-k-k/ 

• “remove — Delete File” on page 495 

• “_rmtmp — Remove Temporary Files” on page 513 

• “<stdio.h>” on page 815 
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uopen — Open Heap for Use 

Format #include <umalloc.h> 

int _uopen(Heap_t heap); 


Description Language Level: Extension 

_uopen allows the current process to use the heap you specify. If the heap is shared, 
you must call _uopen in each process that will allocate or free from the heap. See 
“Managing Memory” in the Programming Guide for more information about sharing 
heaps, and about creating and using heaps in general. 


Return Value If successful, _uopen returns 0. A nonzero return code indicates failure. Passing 
_uopen a heap that is not valid results in undefined behavior. 



This example creates a fixed-size heap, then uses _uopen to open it. The program 
then performs operations on the heap, and closes and destroys it. 

#define INCL_DOSMEMMGR /* Memory Manager values */ 

#include <os2.h> 

linclude <bsememf.h> /* Get flags for memory management */ 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 


int main(void) 

{ 

void *initial_block; 

APIRET rc; 

Heap_t myheap; 
char *p; 


/* Call DosAllocMem to get the initial block of memory */ 
if (0 != (rc = DosAllocMem(&initial_block, 65536, 

PAG_WRITE | PAG_READ j PAGCOMMIT))) { 
printf("DosAl1ocMem error: return code = %ld\n", rc); 
exit(EXITFAILURE); 
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/* Create a fixed size heap starting with the block declared earlier */ 
if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN, 

_HEAP_REGULAR, NULL, NULL))) { 

puts("_ucreate failed."); 
exit(EXIT_FAILURE); 

} 

if (0 != _uopen(myheap)) { 
puts("_uopen failed."); 
exit(EXIT_FAILURE); 

} 

p = _umalloc(myheap, 100); 
free(p); 

if (0 != _uclose(myheap)) { 
puts("_uclose failed"); 
exit(EXIT_FAILURE); 

} 

if (0 != (rc = DosFreeMem(initial_block))) { 

printf("DosFreeMem error: return code = %ld\n", rc); 
exit(EXIT_FAILURE); 

} 

return 0; 


• “_uaddmem — Add Memory to a Heap” on page 683 

• “_uclose — Close Heap from Use” on page 688 

• “_ucreate — Create a Memory Heap” on page 690 

• “Managing Memory” in the Programming Guide 

• “<umalloc.h>” on page 820 
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ustats — Get Information about Heap 

Format #include <umalloc.h> 

int _ustats(Heap_t heap, _HEAPSTATS *hpinfo ); 


Description Language Level: Extension 

_ustats gets information about the heap you specify and stores it in the hpinfo 
structure you pass to it. 


The _HEAPSTATS structure type is defined in <umalloc.h>. The members it contains 
and the information that ustats stores in each is as follows: 


provided 

used 
_ti 1 ed 
shared 
maxfree 


How much memory the heap holds (excluding memory used for 
overhead for the heap) 

How much memory is currently allocated from the heap 
Whether the memory is tiled (_tiled is 1) or not (_tiled is 0) 
Whether the memory is shared (_shared is 1) or not (_shared is 0) 
The size of the largest contiguous piece of memory available on the 
heap 


Return Value 


If successful, _ustats returns 0. A nonzero return code indicates failure. Passing 
_ustats a heap that is not valid results in undefined behavior. 



This example creates a heap and allocates memory from it. It then calls _u stats to 
print out information about the heap. 

#include <stdlib.h> 

#include <stdio.h> 

#include <umal1oc.h> 


int main(void) 

{ 

Heap_t myheap; 

_HEAPSTATS myheap_stat; 
char *ptr; 

/* Use default heap as user heap */ 
myheap = _udefault(NULL); 
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if (NULL == (ptr = _umalloc(myheap, 100))) { 

puts("Cannot allocate memory from user heap."); 
exit(EXIT_FAILURE); 

} 

if (0 != _ustats(myheap, &myheap_stat)) { 
puts("_ustats failed."); 
exit(EXIT_FAILURE); 

} 

printf ("_provided: %u\n", myheap_stat._provided); 
printf ("_used : %u\n", myheap_stat._used); 

printf ("_tiled : %u\n", myheap_stat._tiled); 

printf ("_shared : %u\n", myheap_stat._shared); 

printf ("_max_free: %u\n", myheap_stat._max_free); 
free(ptr); 
return 0; 


/**************************************************************************** 


The output should be similar to : 


provided: 65264 
used : 14304 
tiled : 0 
shared : 0 
max free: 50960 


****************************************************************************/ 


“_mheap — Query Memory Heap for Allocated Object” on page 433 
“_ucreate — Create a Memory Heap” on page 690 
“Managing Memory” in the Programming Guide 
“<umalloc.h>” on page 820 
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utime — Set Modification Time 

Format linclude <sys\utime.h> 

linclude <sys\types.h> 

int utime(char *pathname, struct utimbuf *times); 

Description Language Level: XPG4, xtension 

utime sets the modification time for the file specified by pathname. The process 
must have write access to the file; otherwise, the time cannot be changed. 

Although the utimbuf structure contains a field for access time, only the modification 
time is set in the OS/2 operating system. If times is a NULL pointer, the modification 
time is set to the current time. Otherwise, times must point to a structure of type 
utimbuf, defined in <sys\utime.h>. The modification time is set from the modtime 
field in this structure. 

utime accepts only even numbers of seconds. If you enter an odd number of 
seconds, the function rounds it down. 

Note: In earlier releases of C Set ++, utime began with an underscore (_utime). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _utime to utime for you. 

Return Value utime returns 0 if the file modification time was changed. A return value of -1 
indicates an error, and errno is set to one of the following values: 

Value Meaning 

EACCESS The path name specifies a directory or read-only file. 

EMFILE There are too many open files. You must open the file to change 

its modification time. 

ENOENT The file path name was not found, or the file name was incorrectly 

specified. 

This example sets the last modification time of file utime.dat to the current time. It 
prints an error message if it cannot. 



734 VisualAge C++ C Library Reference 



utime 


linclude <sys\types.h> 
linclude <sys\utime.h> 
linclude <sys\stat.h> 
linclude <stdio.h> 
linclude <stdlib.h> 

Idefine FILENAME "utime.dat" 

int main(void) 

{ 

struct utimbuf ubuf; 
struct stat statbuf; 

FILE *fp; /* File pointer */ 

/* creating file, whose date will be changed by calling utime */ 

fp = fopen(FILENAME, "w"); 


/* write Hello World in the file */ 

fprintf(fp, "Hel1o World\n"); 

/* close file */ 

fclose(fp); 

/* seconds to current date from 1970 Jan 1 */ 

/* Fri Dec 31 23:59:58 1999 */ 

ubuf.modtime = 946702799; 

/* changing file modification time */ 


if (-1 == utime(FILENAME, &ubuf)) { 
perror("utime failed"); 
remove(FILENAME); 
return EX IT_FAILURE; 

} 

/* display the modification time */ 

if (0 == stat(FILENAME, &statbuf)) 

printf("The file modification time is %s", ctime(&statbuf.st_mtime)); 
el se 

printf("Fi1e could not be found\n"); 
remove(FILENAME); 
return 0; 
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ficicicici(iciciticic*-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-ki(-k-k-k-k-k-k-k-k-k-k-kicic-k-ki(-k-k-k-k-k-k-k1(-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

The output should be: 


The file modification time is Fri Dec 31 23:59:58 1999 

*icicieici(-kiciticic*-k-kic-k-ki(-k-k-k-k-k-k-ki(-k-k-kic-k-k-k-k-k-k-k-k-k-k-ki(-k-k-k-k-k-k-ki(-k-k-ki(-k-k-k-k-k-k-k-k-k-k-ki(-k-k-k‘k-k-k-ki(-k-k/ 



“fstat — Information about Open File” on page 281 
“stat — Get Information about File or Directory” on page 561 
“<sys\utime.h>” on page 819 
“<sys\types.h>” on page 819 
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va_arg - va 

Format 

Description 


Return Value 


end - va start — Access Function Arguments 

linclude <stdarg.h> 

var_type va_arg (va_l ist argjptr, var_type ); 

void va_end(va_l ist argjptr)-, 

void va_start(va_list argjptr, variable_name); 

Language Level: ANSI, SAA 

va_arg, va_end, and va_start access the arguments to a function when it takes a fixed 
number of required arguments and a variable number of optional arguments. All 
three of these are macros. You declare required arguments as ordinary parameters to 
the function and access the arguments through the parameter names. 

va_start initializes the argjptr pointer for subsequent calls to va_arg and va_end. 

The argument variablejpame is the identifier of the rightmost named parameter in 
the parameter list (preceding , ...). Use va_start before va_arg. Corresponding 
va_start and va_end macros must be in the same function. 

va_arg retrieves a value of the given var_type from the location given by arg_ptr , 
and increases argjptr to point to the next argument in the list. va_arg can retrieve 
arguments from the list any number of times within the function. The var_type 
argument must be one of int, long, double, struct, union, or pointer, or a typedef of 
one of these types. 

va_end is needed to indicate the end of parameter scanning. 

va_arg returns the current argument. va_end and va_start do not return a value. 
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This example passes a variable number of arguments to a function, stores each 
argument in an array, and prints each argument. 

#include <stdio.h> 

#include <stdarg.h> 


int vout(int max,...); 


int main(void) 

{ 

vout(3, "Sat", "Sun", "Mon"); 
printf("\n"); 

vout(5, "Mon", "Tues", "Wed", "Thurs", "Fri"); 
return 0; 

} 


int vout(int max,...) 

{ 

va_list arg_ptr; 
int args = 0; 
char *days[7]; 

va_start(arg_ptr, max); 
while (args < max) { 

days[args] = va_arg(arg_ptr, char *); 
printf("Day: %s \n", days[args++]); 

} 

va_end(arg_ptr); 

/**************************************************************************** 

The output should be: 

Day: Sat 
Day: Sun 
Day: Mon 

Day: Mon 
Day: Tues 
Day: Wed 
Day: Thurs 
Day: Fri 

****************************************************************************/ 

} 



“vfpri ntf — Print Argument Data to Stream” on page 739 
“vpri ntf — Print Argument Data” on page 741 
“vspri ntf — Print Argument Data to Buffer” on page 743 
“<stdarg.h>” on page 814 
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vfprintf — 

Format 

Description 


Return Value 


Print Argument Data to Stream 

linclude <stdarg.h> 
linclude <stdio.h> 

int vfprintf(FILE *stream, const char *format, va_list arg_ptr ); 

Language Level: ANSI, SAA, XPG4, Extension 

vfprintf formats and writes a series of characters and values to the output stream. 
vfprintf works just like fprintf, except that arg_ptr points to a list of arguments 
whose number can vary from call to call in the program. These arguments should be 
initialized by va_start for each call. In contrast, fprintf can have a list of 
arguments, but the number of arguments in that list is fixed when you compile the 
program. 

vfprintf converts each entry in the argument list according to the corresponding 
format specifier in format. The format has the same form and function as the 
format string for printf. For a description of the format string, see “pri ntf — Print 
Formatted Characters” on page 461. 

In extended mode, vfprintf also converts floating-point values of NaN and infinity to 
the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 

If you specify a null string for the %s or %ls format specifier, vfprintf prints (null). 
(In previous releases of C Set ++, vfpri ntf produced no output for a null string.) 

If successful, vfprintf returns the number of bytes written to stream. If an error 
occurs, the function returns a negative value. 


Chapter 3. Library Functions 739 



vfprintf 



This example prints out a variable number of strings to the file vfprintf .out. 

#include <stdarg.h> 

#include <stdio.h> 

#define FILENAME "vfprintf.o" 


void vout(FILE *stream, char *fmt,...); 


char fmt1[] = "%s %s %s %s\n"; 


int main(void) 

{ 

FILE *stream; 


stream = fopen(FILENAME, "w"); 
vout(stream, fmtl, "Sat", "Sun", "Mon", "Tue"); 
fcl ose(stream); 
return 0; 


/**************************************************************************** 

After running the program, the output file should contain: 


Sat Sun Mon Tue 

■k-kii-k'k'k-k-k'k-k'kicie-kicic-k-k-k-k-k-k'kic-k-kii-k-k'k-k-kick'k-kie-kick-k-k-k-k-k-k'k'kickick-k-k-k-k-k-k'k-kickicick-k-k-k-k-kickick-kic 

} 


/ 


void vout(FILE *stream, char *fmt,...) 

{ 

va_list arg_ptr; 


va_start(arg_ptr, fmt); 
vfprintf(stream, fmt, arg_ptr); 
va_end(arg_ptr); 



“fpri ntf — Write Formatted Data to a Stream” on page 249 
“printf — Print Formatted Characters” on page 461 

“va_arg - va_end - va_start — Access Function Arguments” on page 737 

“vpri ntf — Print Argument Data” on page 741 

“vspri ntf — Print Argument Data to Buffer” on page 743 

“vswprintf — Format and Write Wide Characters to Buffer” on page 745 

“Infinity and NaN Support” on page 33 

“<stdarg.h>” on page 814 

“<stdio.h>” on page 815 
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vprintf — Print Argument Data 

Format linclude <stdarg.h> 

linclude <stdio.h> 

int vprintf(const char *format, va_list argjptr ); 

Description Language Level: ANSI, SAA, XPG4, Extension 

vprintf formats and prints a series of characters and values to stdout. vprintf 
works just like printf, except that arg_ptr points to a list of arguments whose 
number can vary from call to call in the program. These arguments should be 
initialized by va_start for each call. In contrast, printf can have a list of arguments, 
but the number of arguments in that list is fixed when you compile the program. 

vprintf converts each entry in the argument list according to the corresponding 
format specifier in format. The format has the same form and function as the 
format string for printf. For a description of the format string, see “printf — Print 
Formatted Characters” on page 461. 

In extended mode, vprintf also converts floating-point values of NaN and infinity to 
the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 

If you specify a null string for the %s or %ls format specifier, vf pri ntf prints (null). 
(In previous releases of C Set ++, vprintf produced no output for a null string.) 

Return Value If successful, vprintf returns the number of bytes written to stdout. If an error 
occurs, vprintf returns a negative value. 
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This example prints out a variable number of strings to stdout. 

#include <stdarg.h> 

#include <stdio.h> 

void vout(char *fmt, ...); 


int main(void) 

{ 

char fmt1[] = "%s %s %s\n"; 
vout(fmtl, "Sat", "Sun", "Mon"); 
return 0; 


/**************************************************************************** 

The output should be: 


Sat Sun Mon 

■k-kicic-kic-k'kic-k-kicie-kic-k-k-k-k-k-k-k'kicic-kii-k-k'k-k-k-k-k'k-kickick-k-k-k-k-k-k-kicickic-k-k'k-k-kick'k-kickick-k-kick-k-k-kicick-kic 

} 


/ 


void vout(char *fmt, ...) 

{ 

va_list arg_ptr; 


va_start(arg_ptr, fmt); 
vprintf(fmt, arg_ptr); 
va_end(arg_ptr); 



“printf — Print Formatted Characters” on page 461 

“va_arg - va_end - va_start — Access Function Arguments” on page 737 

“vfpri ntf — Print Argument Data to Stream” on page 739 

“vspri ntf — Print Argument Data to Buffer” on page 743 

“<stdarg.h>” on page 814 

“<stdio.h>” on page 815 
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vsprintf — 

Format 

Description 


Return Value 


Print Argument Data to Buffer 

linclude <stdarg.h> 
linclude <stdio.h> 

int vsprintf(char *target-string, const char *format, va_list arg_ptr); 
Language Level: ANSI, SAA, XPG4, Extension 

vsprintf formats and stores a series of characters and values in the buffer 
target-string, vsprintf works just like sprintf, except that arg_ptr points to a 
list of arguments whose number can vary from call to call in the program. These 
arguments should be initialized by va_start for each call. In contrast, sprintf can 
have a list of arguments, but the number of arguments in that list is fixed when you 
compile the program. 

vsprintf converts each entry in the argument list according to the corresponding 
format specifier in format. The format has the same form and function as the 
format string for printf. For a description of the format string, see “pri ntf — Print 
Formatted Characters” on page 461. 

In extended mode, vsprintf also converts floating-point values of NaN and infinity to 
the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the 
string is determined by the format specifiers. See “Infinity and NaN Support” on 
page 33 for more information on infinity and NaN values. 

If you specify a null string for the %s or %ls format specifier, vsprintf prints (null). 
(In previous releases of C Set ++, vspri ntf produced no output for a null string.) 

If successful, vsprintf returns the number of bytes written to target-string. If 
an error occurs, vsprintf returns a negative value. 
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This example assigns a variable number of strings to string and prints the resultant 
string. 

#include <stdarg.h> 

#include <stdio.h> 


void vout(char *string, char *fmt,...); 

char fmt 1 [] = "%s %s %s\n"; 

int main(void) 

{ 

char string[100]; 

vout(string, fmtl, "Sat", "Sun", "Mon"); 
printf("The string is: %s", string); 
return 0; 

/•kit-kic-k-kle-k-kle-k-k-k'k'k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k 

The output should be: 

The string is: Sat Sun Mon 

i 


void vout(char *string, char *fmt,...) 

{ 

va_list arg_ptr; 


va_start(arg_ptr, fmt); 
vsprintf(string, fmt, arg_ptr); 
va_end(arg_ptr); 



“printf — Print Formatted Characters” on page 461 

“spri ntf — Print Formatted Data to Buffer” on page 554 

“swpri ntf — Format and Write Wide Characters to Buffer” on page 635 

“va_arg - va_end - va_start — Access Function Arguments” on page 737 

“vfpri ntf — Print Argument Data to Stream” on page 739 

“vpri ntf — Print Argument Data” on page 741 

“vswprintf — Format and Write Wide Characters to Buffer” on page 745 
“Infinity and NaN Support” on page 33 
“<stdarg.h>” on page 814 
“<stdio.h>” on page 815 
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vswprintf — Format and Write Wide Characters to Buffer 

Format linclude <stdarg.h> 

linclude <wchar.h> 

int vswprintf(wchar_t *wcsbuffer, size_t n, 

const wchar_t * format , va_list argptr); 

Description Language Level: ANSI 93 

vswpri ntf formats and stores a series of wide characters and values in the buffer 
wcsbuffer. vswprintf works just like swprintf, except that argptr points to a list 
of wide-character arguments whose number can vary from call to call. These 
arguments should be initialized by va_start for each call. In contrast, swprintf can 
have a list of arguments, but the number of arguments in that list are fixed when you 
compile in the program. 

The value n specifies the maximum number of wide characters to be written, 
including the terminating null character. 

vswpri ntf converts each entry in the argument list according to the corresponding 
wide-character format specifier in format. The format has the same form and 
function as the format string for printf, with the following exceptions: 

• %c (without an 1 prefix) converts an integer argument to wchar_t, as if by calling 
mbtowc. 

• %lc converts a wint_t to wchar_t. 

• %s (without an 1 prefix); converts an array of multibyte characters to an array of 
wchar_t, as if by calling mbrtowc. The array is written up to, but not including, 
the terminating null character, unless the precision specifies a shorter output. 

• %1 s writes an array of wchar_t. The array is written up to, but not including, the 
terminating null character, unless the precision specifies a shorter output. 

For a complete description of format specifiers, see “printf — Print Formatted 
Characters” on page 461. 

A null wide character is added to the end of the wide characters written; the null 
wide character is not counted as part of the returned value. If copying takes place 
between objects that overlap, the behavior is undefined. 

If you specify a null string for the %s or %ls format specifier, vswprintf prints 
(null). 
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Return Value vswpri ntf returns the number of bytes written in the array, not counting the 
terminating null wide character. 



This example creates a function vout that takes a variable number of wide-character 
arguments and uses vswprintf to print them to wcstr. 


#include <stdio.h> 
#include <stdarg.h> 
#include <wchar.h> 


wchar_t *format3 = L"%ls %d %ls"; 
wchar_t *format5 - L"%ls %d %ls %d %ls"; 

void vout(wchar_t *wcs, size_t n, wchar_t *fmt, ...) 

{ 

va_list arg_ptr; 

va_start(arg_ptr, fmt); 
vswprintf(wcs, n, fmt, arg_ptr); 
va_end(arg_ptr); 
return; 


int main(void) 

{ 

wchar_t wcstr[100]; 


vout(wcstr, 100, format3, L"0NE", 2L, L"THREE"); 
printf("%1s\n", wcstr); 

vout(wcstr, 100, format5, L"0NE", 2L, L"THREE", 4L, L"FIVE"); 
printf("%1s\n", wcstr); 
return 0; 


/**************************************************************************** 
The output should be similar to : 

ONE 2 THREE 

ONE 2 THREE 4 FIVE 

****************************************************************************/ 

} 



“printf — Print Formatted Characters” on page 461 

“swpri ntf — Format and Write Wide Characters to Buffer” on page 635 

“vfpri ntf — Print Argument Data to Stream” on page 739 

“vpri ntf — Print Argument Data” on page 741 

“vspri ntf — Print Argument Data to Buffer” on page 743 

“<stdarg.h>” on page 814 

“<wchar.h>” on page 821 
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wcrtomb — Convert Wide Character to Multibyte Character 

Format linclude <wchar.h> 

int wcrtomb(char *dest, wchar_t wc, mbstate_t *ps); 

Description Language Level: ANSI 93 

wcrtomb is a restartable version of wctomb, and performs the same function. It first 
determines the length of the wide character pointed to by wc. It then converts the 
wide character to the corresponding multibyte character, and stores the converted 
character in the location pointed to by dest , if dest is not a null pointer. A 
maximum of MB_CUR_MAX bytes are stored. 

With wcrtomb, you can switch from one multibyte string to another. On systems that 
support shift states, ps represents the initial shift state of the string (0). If you read in 
only part of the string, wcrtomb sets ps to the string's shift state at the point you 
stopped. You can then call wcrtomb again for that string and pass in the updated ps 
value to continue reading where you left off. 

Note: Because OS/2 does not have shift states, the ps parameter is provided only 
for compatibility with other ANSI/ISO platforms. VisualAge C++ ignores the value 
passed for ps. 

The behavior of wcrtomb is affected by the LC_CTYPE category of the current 
locale. 

Return Value If dest is a null pointer, wcrtomb returns 0. If dest is not a null pointer, wcrtomb 
returns the number of bytes stored in dest. If wc is not a valid wide character, 
wcrtomb sets errno to EILSEQ and returns -1. 

This example uses wcrtomb to convert two wide-character strings to multibyte strings. 

#inc1ude <stdlib.h> 

#inc1ude <stdio.h> 

#inc1ude <1ocale.h> 

#inc1ude <wchar.h> 

Idefine SIZE 20 
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int main(void) 

{ 

wchar_t wcsl[] = L"abc"; 

wchar_t wcs2[] = L"A\x8142" L"C"; 

mbstate_t ssl = 0; 

mbstate_t ss2 = 0; 

size_t lengthl = 0; 

size_t length2 i 0; 

char mbl [SIZE], mb2 [SIZE] ; 

int i; 

if (NULL a= setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

for (i =0; i <=2; ++i) { 

lengthl += wcrtomb(mbl + lengthl, *(wcsl + i), &ssl); 
length2 += wcrtomb(mb2 + length2, *(wcs2 + i), &ss2); 

} 

mblflengthl] = 0; 
mb2[length2] = 0; 

printf("The first multibyte string is: <%s>\n", mbl); 
printf("The second multibyte string is: <%s>\n", mb2); 
return 0; 

/**************************************************************************** 

The output should be similiar to : 

The first multibyte string is: <abc> 

The second multi byte string is: <A BC> 

****************************************************************************/ 

} 



“mbl en — Determine Length of Multibyte Character” on page 411 
“mbrl en — Calculate Length of Multibyte Character” on page 413 
“mbrtowc — Convert Multibyte Character to Wide Character” on page 415 
“mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 
“wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 
“wctomb — Convert Wide Character to Multibyte Character” on page 793 
“<wchar.h>” on page 821 
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wcscat — Concatenate Wide-Character Strings 

Format linclude <wcstr.h> 

wchar_t *wcscat(wchar_t *stringl, const wchar_t *string2 ); 

Description Language Level: SAA, XPG4 

wcscat appends a copy of the string pointed to by string2 to the end of the string 
pointed to by stringl. 

wcscat operates on null-terminated wchar_t strings. The string arguments to this 
function should contain a wchar_t null character marking the end of the string. 
Boundary checking is not performed. 


Return Value wcscat returns a pointer to the concatenated stringl. 



This example creates the wide character string "computer program" using wcscat. 

#include <stdio.h> 
lire!ude <wcstr.h> 

Idefine SIZE 40 


int main(void) 

{ 

wchar_t bufferl[SIZE] = L"computer"; 
wchar_t *string = L" program"; 
wchar_t *ptr; 

ptr = wcscat(bufferl, string); 
printf("bufferl = %ls\n", bufferl); 
return 0; 

/**************************************************************************** 
The output should be: 

bufferl = computer program 

****************************************************************************/ 

i 



“streat — Concatenate Strings” on page 565 

“strncat — Concatenate Strings” on page 595 

“wesneat — Concatenate Wide-Character Strings” on page 764 

“<wcstr.h>” on page 823 
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wcschr — Search for Wide Character 

Format #include <wcstr.h> 

wchar_t *wcschr(const wchar_t *string, wchar_t character); 

Description Language Level: SAA, XPG4 

wcschr searches the wide-character string for the occurrence of character. The 
character can be a wchar_t null character (\0); the wchar_t null character at the end 
of string is included in the search. 

wcschr operates on null-terminated wchar_t strings. The string argument to this 
function should contain a wchar_t null character marking the end of the string. 

Return Value wcschr returns a pointer to the first occurrence of character in string. If the 
character is not found, a NULL pointer is returned. 

This example finds the first occurrence of the character p in the wide-character string 
"computer program". 

#include <stdio.h> 

#include <wcstr.h> 

Idefine SIZE 40 

int main(void) 

{ 

wchar_t bufferl[SIZE] = L"computer program"; 
wchar_t *ptr; 
wchar_t ch = L'p 1 ; 

ptr = wcschr(bufferl, ch); 

printf("The first occurrence of %lc in '%ls' is '%ls'\n", ch, bufferl, ptr); 
return 0; 

j ■k-k-kle-k-k'k-k-k'k-k-k'k-klt'k-k-k'k-k-k'k-k-k'k-k-klc-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-klt'k-kit'k-k-k'k-k-k'k-k-k'k-k-k'k-klt'k-k'k'k-k-k-k-k'k'k-k-k-k 

The output should be: 

The first occurrence of p in 'computer program 1 is 'puter program 1 

■k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-ki<‘k-ki<‘k-k-k‘k-k-k‘k-k-k^ 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “wcsrchr — Locate Wide Character in String” on page 772 
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“wcsspn — Search Wide-Character Strings” on page 776 
“wcswcs — Locate Wide-Character Substring” on page 788 
“<wcstr.h>” on page 823 
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wcscmp — Compare Wide-Character Strings 

Format linclude <wcstr.h> 

int wcscmp(const wchar_t *stringl, const wchar_t *string2 ); 

Description Language Level: SAA, XPG4 

wcscmp compares two wide-character strings. 

wcscmp operates on null-terminated wchar_t strings; string arguments to this function 
should contain a wchar_t null character marking the end of the string. Boundary 
checking is not performed when a string is added to or copied. 


Return Value wcscmp returns a value indicating the relationship between the two strings, as follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

stringl less than string2 
stringl identical to string2 
stringl greater than string2. 



This example compares the wide-character string stringl to string2 using wcscmp. 

#include <stdio.h> 

#include <wcstr.h> 

int main(void) 

{ 

int result; 

wchar_t stringl[] = L"abcdef"; 
wchar_t string2[] = L"abcdefg"; 


result = wcscmp(stringl, string2); 
if (0 == result) 

printf("\"%1s\" is identical to \"%ls\"\n", stringl, string2); 
el se 

if (result < 0) 

printf("\"%1s\" is less than \"%ls\"\n", stringl, string2); 
else 

printf("\"%ls\" is greater than \"%ls\"\n“, stringl, string2); 
return 0; 


/•Jc'k1<‘k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k1e-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k1e-k-k‘k-k-k‘k-k-k-k-k-k‘k-k1<‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k'k 

The output should be: 

"abcdef" is less than "abcdefg" 

-k , k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k'k-k-k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k‘k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k-k‘k-k-k‘k-k-k/ 

} 



“strcmp — Compare Strings” on page 567 

“strcmpi — Compare Strings Without Case Sensitivity” on page 569 
“stri cmp — Compare Strings as Lowercase” on page 591 
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“strnicmp — Compare Strings Without Case Sensitivity” on page 601 
“wcsncmp — Compare Wide-Character Strings” on page 766 
“<wcstr.h>” on page 823 
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wcscoll — Compare Wide-Character Strings 

Format linclude <wchar.h> 

int wcscol1(const wchar_t *wcstrl, const wchar_t *wcstr2 ); 

Description Language Level: ANSI 93, XPG4 

wcscoll compares the wide-character string pointed to by wcstrl to the 
wide-character string pointed to by wcstr2 , both interpreted according to the 
information in the LC_COLLATE category of the current locale. 

wcscoll differs from the wcscmp function, wcscoll performs a comparison between 
two wide-character strings based on language collation rules as controlled by the 
LC_COLLATE category. In contrast, wcscmp performs a wide-character code to 
wide-character code comparison. 

Return Value wcscol 1 returns an integer value indicating the relationship between the strings, as 
listed below: 

Value Meaning 

Less than 0 wcstrl less than wcstr2 

0 wcstrl equivalent to wcstr2 

Greater than 0 wcstrl greater than wcstr2 

If wcsl or wcs2 contain characters outside the domain of the collating sequence, 
wcscol 1 sets errno to EILSEQ. If an error occurs, wcscol 1 sets errno to a nonzero 
value. There is no error return value. 

This example uses wcscol 1 to compare two wide-character strings. 
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#include <wchar.h> 

#include <1ocale.h> 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

wchar_t *wcsl = L"A wide string"; 
wchar_t *wcs2 = L"a wide string"; 
int result; 

if (NULL == setlocale(LC_ALL, LC_C_JAPAN)) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

result = wcscol1(wcsl, wcs2); 
if (0 == result) 

printf("\"%1s\" is identical to \"%ls\"\n", wcsl, wcs2); 
else if (0 > result) 

printf("\"%1s\" is less than \"%ls\"\n", wcsl, wcs2); 
el se 

printf("\"%1s\" is greater than \"%ls\"\n", wcsl, wcs2); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

"A wide string" is identical to "a wide string" 
****************************************************************************/ 

} 


• “strcoll — Compare Strings Using Collation Rules” on page 571 

• “setl ocal e — Set Locale” on page 530 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “<wchar.h>” on page 821 
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wcscpy — Copy Wide-Character Strings 

Format #include <wcstr.h> 

wchar_t *wcscpy(wchar_t *stringl, const wchar_t *string2); 

Description Language Level: SAA, XPG4 

wcscpy copies the contents of string2 (including the ending wchar_t null character) 
into stringl. 

wcscpy operates on null-terminated wchar_t strings; string arguments to this function 
should contain a wchar_t null character marking the end of the string. Boundary 
checking is not performed. 


Return Value wcscpy returns a pointer to stringl. 



This example copies the contents of source to destination. 

#include <stdio.h> 

#include <wcstr.h> 

#define SIZE 40 


int main(void) 

{ 

wchar_t source[SIZE] = L"This is the source string"; 

wchar_t destination[SIZE] = L"And this is the destination string"; 

wchar_t *return_string; 

printf("destination is originally = \"%ls\"\n", destination); 
return_string = wcscpy(destination, source); 

printf("After wcscpy, destination becomes \"%ls\"\n", return_string); 
return 0; 

/**************************************************************************** 

The output should be: 

destination is originally = "And this is the destination string" 

After wcscpy, destination becomes "This is the source string" 
****************************************************************************/ 
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• “strcpy — Copy Strings” on page 573 

• “strdup — Duplicate String” on page 578 

• “strncpy — Copy Strings” on page 599 

• “wcsncpy — Copy Wide-Character Strings” on page 768 

• “<wcstr.h>” on page 823 
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wcscspn — 

Format 

Description 

Return Value 



Find Offset of First Wide-Character Match 

#include <wcstr.h> 

size_t wcscspn(const wchar_t *stringl, const wchar_t *string2); 

Language Level: SAA, XPG4 

wcscspn determines the number of wchar_t characters in the initial segment of the 
string pointed to by stringl that do not appear in the string pointed to by string2. 

wcscspn operates on null-terminated wchar_t strings; string arguments to this function 
should contain a wchar_t null character marking the end of the string. 


wcscspn returns the number of wchar_t characters in the segment. 

This example uses wcscspn to find the first occurrence of any of the characters a, x, 1, 
or e in string. 

#include <stdio.h> 

#include <wcstr.h> 

#define SIZE 40 

int main(void) 

{ 

wchar_t string[SIZE] = L"This is the source string"; 
wchar_t *substring = L"axle"; 

printf("The first %i characters in the string \"%ls\" are not in the " 

"string \"%ls\" \n", wcscspn(string, substring), string, substring); 
return 0; 

/**************************************************************************** 

The output should be: 

The first 10 characters in the string "This is the source string" are 
not in the string "axle"? 

****************************************************************************/ 
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• “strcspn — Compare Strings for Substrings” on page 575 

• “strspn — Search Strings” on page 614 

• “wcsspn — Search Wide-Character Strings” on page 776 

• “wcswcs — Locate Wide-Character Substring” on page 788 

• “<wcstr.h>” on page 823 
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wcsftime — 

Format 

Description 


Return Value 


Convert to Formatted Date and Time 

linclude <wchar.h> 

size_t wcsftime(wchar_t *wdest, size_t maxsize, 

const wchar_t *format, const struct tm *timeptr ); 

Language Level: ANSI 93, XPG4 

wcsftime converts the time and date specification in the timeptr structure into a 
wide-character string. It then stores the null-terminated string in the array pointed to 
by wdest according to the format string pointed to by format, maxsize specifies 
the maximum number of wide characters that can be copied into the array. 

wcsftime works just like strftime, except that it uses wide characters. 

The format string is a multibyte character string containing: 

• Conversion specification characters. 

• Ordinary wide characters, which are copied into the array unchanged. 

The characters that are converted are determined by the LC_CTYPE category of the 
current locale and by the values in the time structure pointed to by timeptr. The 
time structure pointed to by timeptr is usually obtained by calling the gmtime or 
local time function. 

For details on the conversion specifiers you can use in the format string, see 
“strftime — Convert to Formatted Time” on page 586. 

If the total number of wide characters in the resulting string, including the 
terminating null wide character, does not exceed maxsize , wcsftime returns the 
number of wide characters placed into wdest , not including the terminating null wide 
character. Otherwise, wcsftime returns 0 and the contents of the array are 
indeterminate. 
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This example obtains the date and time using local time, formats the information 
with wcsftime, and prints the date and time. 

#include <stdio.h> 

#inc1ude <time.h> 

#include <wchar.h> 

int main(void) 

{ 

struct tm *timeptr; 
wchar_t dest[100]; 
time_t temp; 

size_t rc; 

temp = time(NULL); 
timeptr = 1ocaltime(&temp); 

rc = wcsftime(dest, sizeof(dest)-l, L" Today is %A," 

L" %b %d.\n Time: %I:%M %p", timeptr); 
printf("%d characters placed in string to make:\n\n%ls\n", rc, dest); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

43 characters placed in string to make: 

Today is Thursday, Nov 10. 

Time: 04:56 PM 

****************************************************************************/ 


• “gmtime — Convert Time” on page 321 

• “localtime — Convert Time” on page 385 

• “strftime — Convert to Formatted Time” on page 586 

• “strptime — Convert to Formatted Date and Time” on page 605 

• “<wchar.h>” on page 821 
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wcsid — Determine Character Set ID for Wide Character 

Format linclude <stdlib.h> 

int wcsid(const wchar_t c); 

Description Language Level: Extension 

wcsid determines the character set identifier for the specified wide character wc. You 
can specify character set identifiers for each character in the charmap file for a locale. 
For more information about character set identifiers and charmap files, see the section 
on internationalization in the Programming Guide. 

Return Value wcsid returns the character set identifier for the wide character, or -1 if the wide 
character is not valid. 

This example uses wcsid to get the character set identifier for the wide character A. 

#include <stdio.h> 

#include <stdlib.h> 

int main(void) 

{ 

wchar_t wc = L 1 A 1 ; 
int rc; 

rc = wcsid(wc); 

printf("wide character 1 %c 1 is in character set id %i\n", wc, rc); 
return 0; 

/•k-k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k 

The output should be similar to : 
wide character 'A' is in character set id 0 

ic-k-k-kle-k-kle-k-k'k-k-kle-k-k'k-k-k'k-k-k-k-k-kle-k-k'k-k-k-k-k-kle-k-kle-k-kle-k-k-k-kitle-k-k'k-k-kle-k-k-k-k-kle-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k'k/ 

} 

• “<stdlib.h>” on page 816 

• “csid — Determine Character Set ID for Multibyte Character” on page 126 
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wcslen — Calculate Length of Wide-Character String 

Format linclude <wcstr.h> 

size_t wcslen(const wchar_t *string ); 

Description Language Level: SAA, XPG4 

wcslen computes the number of wide characters in the string pointed to by string. 


Return Value wcslen returns the number of wide characters in string , excluding the terminating 
wchar t null character. 



This example computes the length of the wide-character string string. 

#include <stdio.h> 

#include <wcstr.h> 

int main(void) 

{ 

wchar_t *string = L"abcdef"; 


printf("Length of \"%ls\" is %i\n", string, wcslen(string)); 
return 0; 


/**************************************************************************** 
The output should be: 


Length of "abcdef" is 6 


**************************************************************************** 

i 


/ 



“mbl en — Determine Length of Multibyte Character” on page 411 
“strlen — Determine String Length” on page 593 
“<wcstr.h>” on page 823 
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wcsncat — Concatenate Wide-Character Strings 

Format linclude <wcstr.h> 

wchar_t *wcsncat(wchar_t *stringl, const wchar_t *string2, size_t count); 

Description Language Level: SAA, XPG4 

wcsncat appends up to count wide characters from string2 to the end of stringl, 
and appends a wchar_t null character to the result. 

wcsncat operates on null-terminated wide-character strings; string arguments to this 
function should contain a wchar_t null character marking the end of the string. 

Return Value wcsncat returns stringl. 

This example demonstrates the difference between wcscat and wcsncat. wcscat 
appends the entire second string to the first; wcsncat appends only the specified 
number of characters in the second string to the first. 

#include <stdio.h> 

#include <wcstr.h> 

Idefine SIZE 40 

int main(void) 

{ 

wchar_t bufferl[SIZE] = L"computer"; 
wchar_t *ptr; 

/* Call wcscat with bufferl and " program" */ 

ptr = wcscat(bufferl, L" program"); 
printf("wcscat : bufferl = \"%ls\"\n", bufferl); 

/* Reset bufferl to contain just the string "computer" again */ 

memset(bufferl, L'\0', sizeof(bufferl)); 
ptr = wcscpy(bufferl, L"computer"); 

/* Call wcsncat with bufferl and " program" */ 

ptr = wcsncat(bufferl, L" program", 3); 
printf("wcsncat: bufferl = \"%ls\"\n", bufferl); 
return 0; 

/**************************************************************************** 

The output should be: 

wcscat : bufferl = "computer program" 
wcsncat: bufferl = "computer pr" 

****************************************************************************/ 

} 
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• “strncat — Concatenate Strings” on page 595 

• “strcat — Concatenate Strings” on page 565 

• “wcscat — Concatenate Wide-Character Strings” on page 749 

• “wcsncmp — Compare Wide-Character Strings” on page 766 

• “wcsncpy — Copy Wide-Character Strings” on page 768 

• “<wcstr.h>” on page 823 
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wcsncmp — Compare Wide-Character Strings 

Format linclude <wcstr.h> 

int wcsncmp(const wchar_t *stringl, const wchar_t *string2, size_t count); 

Description Language Level: SAA, XPG4 

wcsncmp compares up to count wide characters in stringl to string2. 

wcsncmp operates on null-terminated wide-character strings; string arguments to this 
function should contain a wchar_t null character marking the end of the string. 


Return Value wcsncmp returns a value indicating the relationship between the two strings, as 
follows: 


Value 
Less than 0 

0 

Greater than 0 


Meaning 

stringl less than string2 
stringl identical to string2 
stringl greater than string2. 



This example demonstrates the difference between wcscmp, which compares the entire 
strings, and wcsncmp, which compares only a specified number of wide characters in 
the strings. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 10 

int main(void) 

{ 

int result; 
int index = 3; 

wchar_t bufferl[SIZE] = L"abcdefg"; 

wchar_t buffer2[SIZE] = L"abcfg"; 

void print_result(int, wchar_t *, wchar_t *); 

result = wcscmp(bufferl, buffer2); 
printf("Comparison of each character\n"); 
printf(" wcscmp: "); 
print_result(result, bufferl, buffer2); 
result = wcsncmp(bufferl, buffer2, index); 

printf("\nComparison of only the first %i characters\n", index); 
printf(" wcsncmp: "); 
print_result(result, bufferl, buffer2); 
return 0; 
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/**************************************************************************** 
The output should be: 

Comparison of each character 
wcscmp: "abcdefg" is less than "abcfg" 

Comparison of only the first 3 characters 
wcsncmp: "abcdefg" is identical to "abcfg" 
****************************************************************************/ 

} 


void print_result(int res,wchar_t *p_bufferl,wchar_t *p_buffer2) 

{ 

if (0 == res) 

printf("\"%1s\" is identical to \"%ls\"\n", p_bufferl, p_buffer2); 
el se 

if (res < 0) 

printf("\"%1s\" is less than \"%ls\"\n", p_bufferl, p_buffer2); 
el se 

printf("\"%1s\" is greater than \"%ls\"\n", p_bufferl, p_buffer2); 


• “strncmp — Compare Strings” on page 597 

• “strcmp — Compare Strings” on page 567 

• “strcoll — Compare Strings Using Collation Rules” on page 571 

• “strcmpi — Compare Strings Without Case Sensitivity” on page 569 

• “stri cmp — Compare Strings as Lowercase” on page 591 

• “strnicmp — Compare Strings Without Case Sensitivity” on page 601 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcsncat — Concatenate Wide-Character Strings” on page 764 

• “wcsncpy — Copy Wide-Character Strings” on page 768 

• “<wcstr.h>” on page 823 
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wcsncpy — Copy Wide-Character Strings 

Format linclude <wcstr.h> 

wchar_t *wcsncpy(wchar_t *stringl, const wchar_t *string2, size_t count); 

Description Language Level: SAA, XPG4 

wcsncpy copies up to count wide characters from string2 to stringl. If string2 is 
shorter than count characters, stringl is padded out to count characters with 
wchar_t null characters. 

wcsncpy operates on null-terminated wide-character strings; string arguments to this 
function should contain a wchar_t null character marking the end of the string. 


Return Value wcsncpy returns a pointer to stringl. 



This example demonstrates the difference between wcscpy, which copies the entire 
wide-character string, and wcsncpy, which copies a specified number of wide 
characters from the string. 


#include <stdio.h> 
#include <wcstr.h> 


#define SIZE 40 

int main(void) 

{ 

wchar_t source[SIZE] = L"123456789"; 
wchar_t sourcel[SIZE] = L"123456789"; 
wchar_t destination[SIZE] = L"abcdefg"; 
wchar_t destinationl[SIZE] = L"abcdefg"; 
wchar_t *return_string; 
int index = 5; 

/* This is how wcscpy works */ 

printf("destination is originally = '%ls'\n", destination); 
return_string = wcscpy(destination, source); 

printf("After wcscpy, destination becomes '%ls'\n\n", return_string); 
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/* This is how wcsncpy works */ 

printf("destinationl is originally = '%ls'\n", destinationl); 
return_string = wcsncpy(destinationl, sourcel, index); 
printf("After wcsncpy, destinationl becomes '%1s'\n", return_string); 
return 0; 

/**************************************************************************** 
The output should be: 

destination is originally = 'abcdefg' 

After wcscpy, destination becomes '123456789' 

destinationl is originally = 'abcdefg' 

After wcsncpy, destinationl becomes '12345fg' 
****************************************************************************/ 


• “strcpy — Copy Strings” on page 573 

• “strncpy — Copy Strings” on page 599 

• “wcscpy — Copy Wide-Character Strings” on page 756 

• “wcsncat — Concatenate Wide-Character Strings” on page 764 

• “wcsncmp — Compare Wide-Character Strings” on page 766 

• “<wcstr.h>” on page 823 
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wcspbrk — Locate Wide Characters in String 

Format #include <wcstr.h> 

wchar_t *wcspbrk(const wchar_t *stringl, const wchar_t *string2); 

Description Language Level: SAA, XPG4 

wcspbrk locates the first occurrence in the string pointed to by stringl of any wide 
character from the string pointed to by string2. 


Return Value wcspbrk returns a pointer to the character. If stringl and string2 have no wide 
characters in common, wcspbrk returns NULL. 



This example uses wcspbrk to find the first occurrence of either a of b in the array 
string. 

#include <stdio.h> 

#include <wcstr.h> 


int main(void) 

{ 

wchar_t *result; 

wchar_t *string = L"A Blue Danube"; 
wchar_t *chars = L"ab"; 

result = wcspbrk(string, chars); 

printf("The first occurrence of any of the characters \"%ls\" in 
"\"%ls\" is \"%ls\"\n", chars, string, result); 
return 0; 



/**************************************************************************** 

The output should be similar to: 

The first occurrence of any of the characters "ab" in "A Blue Danube" 
is "anube" 

****************************************************************************/ 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcsncmp — Compare Wide-Character Strings” on page 766 

• “wcsrchr — Locate Wide Character in String” on page 772 

• “wcsspn — Search Wide-Character Strings” on page 776 
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wcswcs — Locate Wide-Character Substring” on page 788 
<wcstr.h>” on page 823 
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wcsrchr — 

Format 

Description 

Return Value 



Locate Wide Character in String 

#i ncl tide <wcstr.h> 

wchar_t *wcsrchr(const wchar_t *string, wchar_t character ); 

Language Level: SAA, XPG4 

wcsrchr locates the last occurrence of character in the string pointed to by string. 
The terminating wchar_t null character is considered to be part of the string. 


wcsrchr returns a pointer to the character, or a NULL pointer if character does not 
occur in the string. 

This example compares the use of wcschr and wcsrchr. It searches the string for the 
first and last occurrence of p in the wide character string. 

#include <stdio.h> 

#include <wcstr.h> 

#define SIZE 40 

int main(void) 

{ 

wchar_t buf[SIZE] = L"computer program"; 
wchar_t *ptr; 
int ch = 'p' ; 

/* This illustrates wcschr */ 

ptr = wcschr(buf, ch); 

printf("The first occurrence of %c in 1 %1s' is '%ls'\n“, ch, buf, ptr); 

/* This illustrates wscrchr */ 

ptr = wcsrchr(buf, ch); 

printf("The last occurrence of %c in ’%1s' is 1 %1s 1 \n", ch, buf, ptr); 
return 0; 

/**************************************************************************** 

The output should be: 

The first occurrence of p in 'computer program 1 is 'puter program' 

The last occurrence of p in 'computer program' is 'program' 
****************************************************************************/ 
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• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcsspn — Search Wide-Character Strings” on page 776 

• “wcswcs — Locate Wide-Character Substring” on page 788 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “<wcstr.h>” on page 823 
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wcsrtombs 

Format 

Description 


Return Value 


Convert Wide-Character String to Multibyte String 

linclude <wchar.h> 

size_t wcsrtombs (char *dest, const wchar_t **src, 
size_t len, mbstate_t *ps); 

Language Level: ANSI 93 

wcsrtombs is a restartable version of wcstombs, and performs the same function. It 
converts a sequence of wide characters from the array indirectly pointed to by src 
into a sequence of corresponding multibyte characters, and then stores the converted 
characters into the array pointed to by dest. 

Conversion continues up to and including the terminating wchar_t null character. 

The terminating wchar_t null character is also stored. Conversion stops earlier if a 
sequence of bytes does not form a valid multibyte character, or when len codes have 
been stored into the array pointed to by dest. Each conversion takes places as if by 
a call to the wcrtomb function. 

wcsrtombs assigns the object pointed to by src either a null pointer (if conversion 
stopped because a terminating null character was reached) or the address just past the 
last wide character converted. With wcsrtombs, you can switch from one multibyte 
string to another. On systems that support shift states, ps represents the initial shift 
state of the string (0). If you read in only part of the string, wcsrtombs sets ps to the 
string's shift state at the point you stopped. You can then call wcsrtombs again for 
that string and pass in the updated ps value to continue reading where you left off. 

Note: Because OS/2 does not have shift states, the ps parameter is provided only 
for compatibility with other ANSI/ISO platforms. VisualAge C++ ignores the value 
passed for ps. 

The behavior of wcsrtombs is affected by the LC_CTYPE category of the current 
locale. 

wcsrtombs returns the number of bytes in the resulting multibyte character sequence 
pointed to by dest. If dest is a null pointer, the value of len is ignored and 
wcsrtombs returns the number of elements required for the converted wide characters. 

If the input string contains an invalid wide character, wcsrtombs sets errno to 
EILSEQ and returns (size_t)-l. 
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This example uses wcsrtombs to convert two wide-character strings to multibyte 
character strings. 


#include <stdlib.h> 
#include <stdio.h> 
#include <1ocale.h> 
#include <wchar.h> 


#define SIZE 20 


int main(void) 

{ 


wchar_t 

wchar_t 

const wchar_t 

const wchar_t 

mbstate_t 

mbstate_t 

char 


L''abc"; 

L"A\x8142" L"C"; 
wcsl; 


wcsl[] = 
wcs2[] = 

*pwcsl = 

*pwcs2 = wcs2; 
ssl = 0; 
ss2 = 0; 

mbl[SIZE] , mb2[SIZE]; 


if (NULL == setlocale(LC_ALL, "ja_jp.ibm-932")) { 
printf("setlocale failed.\n"); 
exit(EXITFAILURE); 

} 

wcsrtombs(mbl, &pwcsl, SIZE, &ssl); 
wcsrtombs(mb2, &pwcs2, SIZE, &ss2); 
printf("The first multibyte string is: <%s>\n", mbl); 
printf("The second multibyte string is: <%s>\n", mb2); 
return 0; 


/**************************************************************************** 
The output should be similiar to : 

The first multi byte string is: <abc> 

The second multi byte string is: <A BC> 

****************************************************************************/ 

} 


• “mbl en — Determine Length of Multibyte Character” on page 411 

• “mbrlen — Calculate Length of Multibyte Character” on page 413 

• “mbrtowc — Convert Multibyte Character to Wide Character” on page 415 

• “mbsrtowcs — Convert Multibyte String to Wide-Character String” on page 418 

• “mbstowcs — Convert Multibyte String to Wide-Character String” on page 420 

• “wcrtomb — Convert Wide Character to Multibyte Character” on page 747 

• “wcstombs — Convert Wide-Character String to Multibyte String” on page 784 

• “<wchar.h>” on page 821 
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wcsspn — Search Wide-Character Strings 

Format linclude <wcstr.h> 

size_t wcsspn(const wchar_t *stringl, const wchar_t *string2 ); 

Description Language Level: SAA, XPG4 

wcsspn scans stringl for the wide characters contained in string2. It stops when it 
encounters a character in stringl that is not in string2. 

Return Value wcsspn returns the number of wide characters from string2 that it found in 
stringl. 

This example finds the first occurrence in the array string of a wide character that is 
not an a, b, or c. Because the string in this example is cabbage, wcsspn returns 5, the 
index of the segment of cabbage before a character that is not an a, b, or c. 

#include <stdio.h> 

#include <wcstr.h> 

int main(void) 

{ 

wchar_t *string = L"cabbage"; 
wchar_t *source = L"abc"; 
int index; 

index = wcsspn(string, L"abc"); 

printf("The first %d characters of \"%ls\" are found in \"%ls\"\n", index, 
string, source); 
return 0; 

/•k-k-klc-k-k'k-k-k'k-k-k'k-k-k'k-kit'k-k-k'k-k-k-k-k-k'k-k'k'k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-kit'k-k-k'k-k'k-k-k-k'k 

The output should be: 

The first 5 characters of "cabbage" are found in "abc" 

■k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k , k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k-k-k1<‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k-k‘k-k1(/ 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcsrchr — Locate Wide Character in String” on page 772 

• “wcsspn — Search Wide-Character Strings” 

• “wcswcs — Locate Wide-Character Substring” on page 788 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “<wcstr.h>” on page 823 
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wcsstr — Locate Wide-Character Substring 

Format linclude <wchar.h> 

wchar_t *wcsstr(const wchar_t *wcsl, const wchar_t *wcs2) ; 

Description Language Level: ANSI 93 

wcsstr locates the first occurrence of wcs2 in wcsl. In the matching process, wcsstr 
ignores the wchar_t null character that ends wcs2. 

The behavior of wcsstr is affected by the LC_CTYPE category of the current locale. 

Return Value wcsstr returns a pointer to the beginning of the first occurrence of wcs2 in wcsl. 

If wcs2 does not appear in wcsl , wcsstr returns NULL. If wcs2 points to a 
wide-character string with zero length, wcsstr returns wcsl. 

This example uses wcsstr to find the first occurrence of hay in the wide-character 
string needle in a haystack. 

#inc1ude <stdio.h> 

#inc1ude <wchar.h> 

int main(void) 

{ 

wchar_t *wcsl = L"needle in a haystack"; 
wchar_t *wcs2 = L"hay"; 

printf("result: \"%ls\"\n", wcsstr(wcsl, wcs2)); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

result: "haystack" 

****************************************************************************/ 

} 

• “strstr — Locate Substring” on page 616 

• “wcschr — Search for Wide Character” on page 750 

• “wcsrchr — Locate Wide Character in String” on page 772 

• “wcswcs — Locate Wide-Character Substring” on page 788 

• “<wchar.h>” on page 821 
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wcstod — Convert Wide-Character String to Double 

Format linclude <wchar.h> 

double wcstod(const wchar_t *nptr, wchar_t **endptr ); 

Description Language Level: ANSI 93, XPG4 

wcstod converts the wide-character string pointed to by nptr to a double value. The 
nptr parameter points to a sequence of characters that can be interpreted as a 
numerical value of type double, wcstod stops reading the string at the first character 
that it cannot recognize as part of a number. This character can be the wchar_t null 
character at the end of the string. 

wcstod expects nptr to point to a string with the following form: 



1 ■-<»' r n s' n ' 1 rl i n ■» «■* 


r\f fl L U c “ o jt/L/C c I U L y t L j i j j i 

J L- . -* ^—digits-* 

. —digits - - - 

►—[- 

1 — | —e— | — - — digits— 1 

1—E_l -+- 


Note: The character used for the decimal point (shown as . in the above diagram) 
depends on the LC_NUMERIC category of the current locale. 

In locales other than the "C" locale, additional implementation-defined subject 
sequence forms may be accepted. 

The behavior of wcstod is affected by the LC_CTYPE category of the current locale. 

Return Value wcstod function returns the converted double value. If no conversion could be 

performed, wcstod returns 0. If the correct value is outside the range of representable 
values, wcstod returns +HUGE_VAL or -HUGE_VAL (according to the sign of the 
value), and sets errno to ERANGE. If the correct value would cause underflow, 
wcstod returns 0 and sets errno to ERANGE. 

If the string nptr points to is empty or does not have the expected form, no 
conversion is performed, and the value of nptr is stored in the object pointed to by 
endptr, provided that endptr is not a null pointer. 
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This example uses wcstod to convert the string wcs to a floating-point value. 

#include <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

wchar_t *wcs = L"3.1415926This stopped it"; 
wchar_t *stopwcs; 

printf("wcs = \"%ls\"\n", wcs); 
printf(" wcstod = %f\n", wcstod(wcs, &stopwcs)); 
printf(" Stop scanning at \"%ls\"\n", stopwcs); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

wcs = "3.1415926This stopped it" 
wcstod = 3.141593 
Stop scanning at "This stopped it" 

****************************************************************************/ 


• “strtod — Convert Character String to Double” on page 621 

• “strtol — Convert Character String to Long Integer” on page 625 

• “strtol d — Convert String to Long Double” on page 627 

• “strtoul — Convert String Segment to Unsigned Integer” on page 629 

• “wcstol — Convert Wide-Character to Long Integer” on page 782 

• “wcstoul — Convert Wide-Character String to Unsigned Long” on page 786 

• “<wchar.h>” on page 821 
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wcstok — Tokenize Wide-Character String 

Format linclude <wchar.h> 

wchar_t *wcstok(wchar_t *wcsl, const wchar_t *wcs2, wchar_t **ptr ); 

Description Language Level: ANSI 93, XPG4 

wcstok reads wcsl as a series of zero or more tokens and wcs2 as the set of wide 
characters serving as delimiters for the tokens in wcsl. A sequence of calls to 
wcstok locates the tokens inside wcsl. The tokens can be separated by one or more 
of the delimiters from wcs2. The third argument points to a wide-character pointer 
that you provide where wcstok stores information necessary for it to continue 
scanning the same string. 

When wcstok is first called for the wide-character string wcsl, it searches for the first 
token in wcsl, skipping over leading delimiters, wcstok returns a pointer to the first 
token. 

To read the next token from wcsl, call wcstok with NULL as the first parameter 
(wcsl). This NULL parameter causes wcstok to search for the next token in the 
previous token string. Each delimiter is replaced by a null character to terminate the 
token. 

wcstok always stores enough information in the pointer ptr so that subsequent calls, 
with NULL as the first paramter and the unmodified pointer value as the third, will 
start searching right after the previously returned token. You can change the set of 
delimiters ( wcs2) from call to call. 

The behavior of wcstok function is affected by the LC_CTYPE category of the 
current locale. 

Return Value wcstok function returns a pointer to the first wide character of the token, or a null 

pointer if there is no token. In later calls with the same token string, strtok returns 
a pointer to the next token in the string. When there are no more tokens, strtok 
returns NULL. 
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This example uses wcstok to locate the tokens in the wide-character string strl. 

#include <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

static wchar_t strl[] = L"?a??b,,,#c"; 
static wchar_t str2[] = L"\t \t"; 
wchar_t *t, *ptrl, *ptr2; 


t = wcstok(strl. 

L"? 

", &ptrl); 

/* 

t points to 

the token 

L"a" 

*/ 

printf("t = 1 %1s 1 

An" 

, t); 






t = wcstok(NULL, 

L", 

", &ptrl); 

/* 

t points to 

the token 

L"?b" 

*/ 

printf("t = '%ls 

An" 

, t); 






t = wcstok(str2. 

L" 

\t,“, &ptr2); 

/* 

t is a null 

pointer 


*/ 

printf("t = 1 %1s 1 

An" 

, t); 






t = wcstok(NULL, 

L"# 

,", &ptrl); 

/* 

t points to 

the token 

L"c" 

*/ 

printf("t = '%ls 

\n" 

, t); 






t = wcstok(NULL, 

L"? 

", &ptrl); 

/* 

t is a null 

pointer 


*/ 

printf("t = 1 %1s 1 

An" 

, t); 







return 0; 

/**************************************************************************** 
The output should be similar to : 

t = 'a' 
t = 1 ?b' 
t = 1 (nul1) 1 
t = 1 c 1 
t = 1 (nul1) 1 

****************************************************************************/ 

} 


• “strtok — Tokenize String” on page 623 

• “<wchar.h>” on page 821 
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wcstol — Convert Wide-Character to Long Integer 

Format linclude <wchar.h> 

long int wcstol(const wchar_t *nptr, wchar_t **endptr, int base); 

Description Language Level: ANSI 93, XPG4 

wcstol converts the wide-character string pointed to by nptr to a long integer value. 
nptr points to a sequence of wide characters that can be interpreted as a numerical 
value of type long int. wcstol stops reading the string at the first wide character 
that it cannot recognize as part of a number. This character can be the wchar_t null 
character at the end of the string. The ending character can also be the first numeric 
character greater than or equal to the base. 

When you use wcstol, nptr should point to a string with the following form: 



white-space-^ 



1 1 1 

o o o 

X X I 

1 1 1 

digits-^ 


If base is in the range of 2 through 36, it becomes the base of the number. If base 
is 0, the prefix determines the base (8, 16, or 10): the prefix 0 means base 8 (octal); 
the prefix Ox or OX means base 16 (hexadecimal); using any other digit without a 
prefix means decimal. 

In locales other than the "C" locale, additional implementation-defined forms may be 
accepted. 

The behavior of wcstol is affected by the LC_CTYPE category of the current locale. 

Return Value wcstol returns the converted long integer value. If no conversion could be 

performed, wcstol returns 0. If the correct value is outside the range of representable 
values, wcstol returns LONG_MAX or LONG_MIN returned (according to the sign 
of the value), and sets errno to ERANGE. 

If the string nptr points to is empty or does not have the expected form, no 
conversion is performed, and the value of nptr is stored in the object pointed to by 
endptr, provided that endptr is not a null pointer. 
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This example uses wcstol to convert the wide-character string wcs to a long integer 
value. 

#inc1ude <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

wchar_t *wcs = L"10110134932"; 
wchar_t *stopwcs; 
long 1; 

int base; 

printf("wcs = \"%ls\"\n", wcs); 
for (base=2; base<=8; base*=2) { 

1 = wcstol(wcs, &stopwcs, base); 
printf(" wcstol = %ld\n" 

" Stopped scan at \"%1s\"\n\n", 1, stopwcs); 


return 0; 

/**************************************************************************** 

The output should be similar to : 

wcs = "10110134932" 
wcstol = 45 

Stopped scan at "34932" 

wcstol = 4423 
Stopped scan at "4932" 

wcstol = 2134108 
Stopped scan at "932" 

****************************************************************************/ 

} 

• “atol — Convert Character String to Long Integer” on page 67 

• “strtol — Convert Character String to Long Integer” on page 625 

• “strtol d — Convert String to Long Double” on page 627 

• “strtoul — Convert String Segment to Unsigned Integer” on page 629 

• “wcstod — Convert Wide-Character String to Double” on page 778 

• “wcstoul — Convert Wide-Character String to Unsigned Long” on page 786 

• “<wchar.h>” on page 821 
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wcstombs — 

Format 

Description 


Return Value 



Convert Wide-Character String to Multibyte String 

linclude <stdlib.h> 

size_t wcstombs(char *dest, const wchar_t *string, size_t n ); 

Language Level: ANSI, SAA, XPG4 

wcstombs converts the wide-character string pointed to by string into the multibyte 
array pointed to by dest. The conversion stops after n bytes in dest are filled or 
after a wide null character is encountered. 

Only complete multibyte characters are stored in dest. If the lack of space in dest 
would cause a partial multibyte character to be stored, wcstombs stores fewer than n 
bytes and discards the invalid character. 

The behavior of wcstombs is affected by the LC_CTYPE category of the current 
locale. 

If successful, wcstombs returns the number of bytes converted and stored in dest, 
not counting the terminating null character. The string pointed to by dest ends with 
a null character unless wcstombs returns the value n. 

If it encounters an invalid wide character, wcstombs returns (size_t)-l. 

If the area pointed to by des t is too small to contain all the wide characters 
represented as multibyte characters, wcstombs returns the number of bytes containing 
complete multibyte characters. 

If dest is a null pointer, the value of len is ignored and wcstombs returns the 
number of elements required for the converted wide characters. 

In this example, wcstombs converts a wide-character string to a multibyte character 
string twice. The first call converts the entire string, while the second call only 
converts three characters. The results are printed each time. 
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#include <stdio.h> 

#include <stdlib.h> 

Idefine SIZE 20 

int main(void) 

{ 

char dest [SIZE]; 
wchar_t *dptr = L"string"; 
size_t count = SIZE; 
size_t length; 

length = wcstombs(dest, dptr, count); 

printf("%d characters were converted.\n", length); 

printf("The converted string is \"%s\"\n\n", dest); 

/* Reset the destination buffer */ 

memset(dest, '\0', sizeof(dest)); 

/* Now convert only 3 characters */ 

length = wcstombs(dest, dptr, 3); 
printf("%d characters were converted.\n", length); 
printf("The converted string is \"%s\"\n", dest); 
return 0; 

/**************************************************************************** 
The output should be: 

6 characters were converted. 

The converted string is "string" 

3 characters were converted. 

The converted string is "str" 

****************************************************************************/ 


• “mbstowcs — Convert Multibyte String to Wide-Character String” on page 420 

• “wcslen — Calculate Length of Wide-Character String” on page 763 

• “wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 

• “wctomb — Convert Wide Character to Multibyte Character” on page 793 

• “<stdlib.h>” on page 816 
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wcstoul — Convert Wide-Character String to Unsigned Long 

Format linclude <wchar.h> 

unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base); 

Description Language Level: ANSI, SAA, XPG4 

wcstoul converts the wide-character string pointed to by nptr to an unsigned long 
integer value, nptr points to a sequence of wide characters that can be interpreted 
as a numerical value of type unsigned long int. wcstoul stops reading the string at 
the first wide character that it cannot recognize as part of a number. This character 
can be the wchar_t null character at the end of the string. The ending character can 
also be the first numeric character greater than or equal to the base. 

When you use wcstoul, nptr should point to a string with the following form: 



white-space-^ 

o o o 

X X I 

1 T 1 

digits-^ 


If base is in the range of 2 through 36, it becomes the base of the number. If base 
is 0, the prefix determines the base (8, 16, or 10): the prefix 0 means base 8 (octal); 
the prefix Ox or OX means base 16 (hexadecimal); using any other digit without a 
prefix means decimal. 

In locales other than the "C" locale, additional implementation-defined subject 
sequence forms may be accepted. 

If the subject sequence is empty or does not have the expected form, no conversion is 
performed and wcstoul stores the value of nptr in the object pointed to by endptr, 
provided that endptr is not a null pointer. 

The behavior of wcstoul is affected by the LC_CTYPE category of the current 
locale. 

Return Value wcstoul returns the converted unsigned long integer value. If no conversion could 
be performed, wcstoul returns 0. If the correct value is outside the range of 
representable values, wcstoul returns ULONG_MAX and sets errno to ERANGE. 

If the string nptr points to is empty or does not have the expected form, no 
conversion is performed, and the value of nptr is stored in the object pointed to by 
endptr, provided that endptr is not a null pointer. 
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This example uses wcstoul to convert the string wcs to an unsigned long integer 
value. 

#include <stdio.h> 

#inc1ude <wchar.h> 

Idefine BASE 2 

int main(void) 

{ 

wchar_t *wcs = L"lO0Oel3 camels"; 
wchar_t *endptr; 
unsigned long int answer; 

answer = wcstoul(wcs, &endptr, BASE); 
printff'The input wide string used: 1 %1 s 1 \n" 

"The unsigned long int produced: %lu\n" 

"The substring of the input wide string that was not" 

" converted to unsigned long: '%ls'\n", wcs, answer, endptr); 
return 0; 

/**************************************************************************** 

The output should be similar to : 

The input wide string used: '100Oel3 camels' 

The unsigned long int produced: 8 

The substring of the input wide string that was not converted to 
unsigned long: 'el3 camels' 

****************************************************************************/ 


• “strtod — Convert Character String to Double” on page 621 

• “strtol — Convert Character String to Long Integer” on page 625 

• “strtol — Convert Character String to Long Integer” on page 625 

• “strtol d — Convert String to Long Double” on page 627 

• “wcstod — Convert Wide-Character String to Double” on page 778 

• “wcstol — Convert Wide-Character to Long Integer” on page 782 

• “<wchar.h>” on page 821 
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wcswcs — Locate Wide-Character Substring 

Format linclude <wcstr.h> 

wchar_t *wcswcs(const wchar_t *stringl, const wchar_t *string2 ); 

Description Language Level: SAA, XPG4 

wcswcs locates the first occurrence of string2 in the wide-character string pointed to 
by stringl. In the matching process, wcswcs ignores the wchar_t null character that 
ends string2. 


Return Value wcswcs returns a pointer to the located string or NULL if the string is not found. If 
string2 points to a string with zero length, wcswcs returns stringl. 



This example finds the first occurrence of the wide character string pr in bufferl. 

#include <stdio.h> 

#include <wcstr.h> 

#define SIZE 40 


int main(void) 

{ 

wchar_t bufferl[SIZE] = L"computer program"; 
wchar_t *ptr; 
wchar_t *wch = L"pr"; 


ptr = wcswcs(bufferl, wch); 

printf("The first occurrence of %ls in 1 %1s 1 is '%ls'\n", wch, bufferl, ptr); 
return 0; 



/•k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-kle-k-kle-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k-k-k-k-k-k-kle-k-k'k-k-klck-k-k-k-klck-k-k-k-k-k 

The output should be: 

The first occurrence of pr in 'computer program 1 is 'program 1 

■kle-kltle-k-k'k-kltlc-k-kle-klt-k'k-k-k-k-kle-k-k-k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-klt'k-k-k'k-klt'k'k-k-k-k-k'k-k-k'k-k-k j 

} 

• “strchr — Search for Character” on page 566 

• “strcspn — Compare Strings for Substrings” on page 575 

• “strpbrk — Find Characters in String” on page 604 

• “strrchr — Find Last Occurrence of Character in String” on page 610 

• “strspn — Search Strings” on page 614 

• “wcschr — Search for Wide Character” on page 750 

• “wcscspn — Find Offset of First Wide-Character Match” on page 758 

• “wcspbrk — Locate Wide Characters in String” on page 770 

• “wcsrchr — Locate Wide Character in String” on page 772 

• “wcsspn — Search Wide-Character Strings” on page 776 

• “<wcstr.h>” on page 823 


788 VisualAge C++ C Library Reference 




wcswidth 


wcswidth — Determine Display Width of Wide-Character String 

Format linclude <wchar.h> 

int wcswidth (const wchar_t *wcs, size_t n ); 

Description Language Level: XPG4 

wcswidth determines the number of printing positions occupied on a display device 
by a graphic representation of n wide characters in the string pointed to by wcs (or 
fewer than n wide characters, if a null wide character is encountered before n 
characters have been exhausted). The number is independent of its location on the 
device. 


The behavior of wcswidth is affected by the LC_CTYPE category. 


Return Value wcswidth returns the number of printing positions occupied by the wide-character 
string. If wcs points to a null wide character, wcswidth returns 0. If any wide 
character in wcs is not a printing character, wcswidth returns -1. 

Note: Under VisualAge C++, the printing width is 0 for a null character, 1 for each 
single-byte character, and 2 for each double-byte character. 



This example uses wcswidth to calculate the display width of ABC. 

#inc1ude <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

wchar_t *wcs = L"ABC"; 


printf("wcs has a width of: %d\n", wcswidth(wcs,3)); 
return 0; 


/**************************************************************************** 
The output should be similar to : 

wcs has a width of: 3 

****************************************************************************/ 

i 



“wcwidth — Determine Display Width of Wide Character” on page 798 
“<wchar.h>” on page 821 
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wcsxfrm — Transform Wide-Character String 

Format linclude <wchar.h> 

size_t wcsxfrm(wchar_t *wcsl, const wchar_t *wcs2, size_t n ); 

Description Language Level: ANSI 93, XPG4 

wcsxfrm transforms the wide-character string pointed to by wcs2 to values that 
represent character collating weights and places the resulting wide-character string 
into the array pointed to by wcsl. The transformation is determined by the program's 
locale. The transformed string is not necessarily readable, but can be used with the 
wcscmp function. 

The transformation is such that if wcscmp were applied to two transformed 
wide-character strings, the results would be the same as applying the wcscol 1 
function to the two corresponding untransformed strings. 

No more than n elements are placed into the resulting array pointed to by wcsl, 
including the terminating null wide character. If n is 0, wcsl can be a null pointer. 

If copying takes place between objects that overlap, the behavior is undefined. 

The behavior of wcsxfrm is controlled by the LC_COLLATE category of the current 
locale. 


Return Value wcsxfrm returns the length of the transformed wide-character string (excluding the 
terminating null wide character). If the value returned is n or more, the contents of 
the array pointed to by wcsl are indeterminate. 

If wcsl is a null pointer, wcsxfrm returns the number of elements required to contain 
the transformed wide string. 

If wcs2 contains invalid wide characters, wcsxfrm returns (size_t)-l. The 
transformed values of the invalid characters are either less than or greater than the 
transformed values of valid wide characters, depending on the option chosen for the 
particular locale definition. 

If wcs2 contains wide characters outside the domain of the collating sequence, 
wcsxfrm sets errno to EILSEQ. 



This example uses wcsxfrm to transform two different strings with the same collating 
weight. It then uses wcscmp to compare the new strings. 
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#include <stdlib. h> 

#include <stdio.h> 

#include <1ocale.h> 

#include <wchar.h> 

int main(void) 

{ 

wchar_t *stringl = L"stride ngl"; 
wchar_t *string2 = L"stri*ngl"; 
wchar_t *newstringl, *newstring2; 
int lengthl, length2; 

if (NULL == setlocale(LC_ALL, LC_C_FRANCE)) { 
printf("setlocale failed.\n"); 
exit(EXIT_FAILURE); 

} 

lengthl = wcsxfrm(NULL, stringl, 0); 

length2 = wcsxfrm(NULL, string2, 0); 

if (NULL == (newstringl = cal 1oc(lengthl + 1, sizeof(wchar_t))) | 

NULL == (newstring2 = cal 1oc(length2 + 1, sizeof(wchar_t)))) { 

printf("insufficient memory\n"); 
exit(EXIT_FAILURE); 

} 

if ((wcsxfrm(newstringl, stringl, lengthl + 1) != lengthl) | 
(wcsxfrm(newstring2, string2, length2 + 1) != 1ength2)) { 
printf("error in string processing\n"); 
exit(EXITFAILURE); 

} 

if (0 != wcscmp(newstringl, newstring2)) 
printf("wrong results\n"); 
el se 

printf("correct results\n"); 
return 0; 

/**************************************************************************** 
The output should be similar to : 

correct results 

****************************************************************************/ 

} 


• “strxfrm — Transform String” on page 632 

• “wcscmp — Compare Wide-Character Strings” on page 752 

• “wcscoll — Compare Wide-Character Strings” on page 754 

• “<wchar.h>” on page 821 
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wctob — Convert Wide Character to Byte 

Format linclude <stdio.h> 

linclude <wchar.h> 
int wctob (wint_t ivc); 

Description Language Level: ANSI 93 

wctob determines whether wc corresponds to a member of the extended character set, 
whose multibyte character has a length of 1 byte 

The behavior of wctob is affected by the LC_CTYPE category of the current locale. 

Return Value If C corresponds to a multibyte character with a length of 1 byte, wctob returns the 
single-byte representation. Otherwise, wctob returns EOF. 

This example uses wctob to test if the wide character A is a valid single-byte 
character. 

#include <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

wint_t wc = L 1 A' ; 
if (wctob(wc) == wc) 

printf("%lc is a valid single byte character\n", wc); 
else 

printf("%lc is not a valid single byte character\n", wc); 
return 0; 

/■k-k-k'k-k-k'k-k-k'k-k-k'k-klt'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-klc-k-k'k-k-klc-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k 

The output should be similar to : 

A is a valid single byte character 

■k'k-k-kle-k-kle-k-k'k-k-k'k-k-kle-k-k'k-k-k-k-k-k'k-k-kle-k-k'k-k-k'k-k-k'k-k-k'k-k-k-k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-k-k'k-kit'k-k-k'k-k-k'k-k'k/ 

} 

• “mbtowc — Convert Multibyte Character to Wide Character” on page 422 

• “wctomb — Convert Wide Character to Multibyte Character” on page 793 

• “wcstombs — Convert Wide-Character String to Multibyte String” on page 784 

• “<wchar.h>” on page 821 
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wctomb — Convert Wide Character to Multibyte Character 

Format linclude <stdlib.h> 

int wctomb(char *string, wchar_t wc); 


Description Language Level: ANSI, SAA, XPG4 

wctomb converts the wide character wc into a multibyte character and stores it in the 
location pointed to by string, wctomb stores a maximum of MB_CUR_MAX characters 
in string. 

The behavior of wctomb is affected by the LC_CTYPE category of the current locale. 


Return Value wctomb returns the length in bytes of the multibyte character. If wc is not a valid 
multibyte character, wctomb returns -1. 

If string is a NULL pointer, wctomb returns 0. 

Note: On platforms that support shift states, wctomb can also return a nonzero value 
to indicate that the multibyte encoding is state dependent. Because VisualAge C++ 
does not support state-dependent encoding, wctomb always returns 0 when string is 
NULL. 



This example calls wctomb to convert the wide character c to a multibyte character. 

#include <stdio.h> 
line!ude <wcstr.h> 

Idefine SIZE 40 


int main(void) 

{ 

static char buffer[SIZE]; 
wchar_t wch = L'c'; 
int length; 

length = wctomb(buffer, wch); 

printf("The number of bytes that comprise the multibyte ""character is %i\n", 
length); 

printf("And the converted string is \"%s\"\n", buffer); 
return 0; 

/**************************************************************************** 
The output should be: 

The number of bytes that comprise the multi byte character is 1 
And the converted string is "c" 

****************************************************************************/ 



“mbtowc — Convert Multibyte Character to Wide Character” on page 422 
“wertomb — Convert Wide Character to Multibyte Character” on page 747 
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• “wcsl en — Calculate Length of Wide-Character String” on page 763 

• “wcsrtombs — Convert Wide-Character String to Multibyte String” on page 774 

• “wcstombs — Convert Wide-Character String to Multibyte String” on page 784 

• “wctob — Convert Wide Character to Byte” on page 792 

• “<stdlib.h>” on page 816 
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wctype — Get Handle for Character Property Classification 

Format linclude <wctype.h> 

wctype_t wctype(const char *property); 

Description Language Level: ANSI 93, XPG4 

wctype returns a handle for the specified character class from the LC_CTYPE 
category. You can then use this handle with the i swctype function to determine if a 
given wide character belongs to that class. 

The following strings correspond to the standard (basic) character classes or 
properties: 

"alnum" "cntrl" "lower" "space" 

"alpha" "digit" "print" "upper" 

"blank" "graph" "punct" "xdigit" 

These classes are described in “isalnum to isxdigit — Test Integer Value” on 
page 347 and “iswalnum to iswxdigit — Test Wide Integer Value” on page 360. 

You can also give the name of a user-defined class, as specified in a locale definition 
file, as the property argument. 

The behavior of this wide-character function is affected by the LC_CTYPE category 
of the current locale. 

Return Value wctype returns a value of type wctype_t that represents the property and can be 

used in calls to i swctype. If the given property is not valid for the current locale 
(LC_CTYPE category), wctype returns 0. 

Values returned by wctype are valid until a call to setlocale that modifies the 
LC_CTYPE category. 
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This example uses wctype to return each standard property, and calls i swctype to 
test a wide character against each property. 

#include <wctype.h> 

#include <stdio.h> 


#define UPPER_LIMIT OxFF 

int main(void) 

{ 

int wc; 

for (wc = 0; wc <= UPPER_LIMIT; wc++) { 


printf("%#4x 

". wc); 





printf("%c", 

iswctype(wc. 

wctype("print")) 

? 

wc 

1 '); 

printf("%s", 

iswctype(wc. 

wctype("alnum")) 

? 

" AN" 

" ') 

printf("%s", 

iswctype(wc. 

wctype("alpha")) 

? 

" A " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("blank")) 

? 

" B " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("cntrl")) 

? 

" C " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("digit")) 

? 

" D " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("graph")) 

? 

" G " 

■ ') 

printf("%s", 

iswctype(wc. 

wctype("lower")) 

? 


‘ ") 

printf("%s", 

iswctype(wc. 

wctype("punct")) 

? 

" PU" 

" ") 

printf("%s", 

iswctype(wc. 

wctype("space")) 

? 

" S " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("print")) 

? 

" PR" 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("upper")) 

? 

" U " 

■ ") 

printf("%s", 

iswctype(wc. 

wctype("xdigit")) 

? 

" X " 

■ ") 


putchar( 1 \n 1 ); 

} 

return 0; 

/**************************************************************************** 

The output should be similar to : 


Oxlf C 


0x20 

B 


S 

PR 

0x21 ! 


G 

PU 

PR 

0x22 " 


G 

PU 

PR 

0x23 # 


G 

PU 

PR 

0x24 $ 


G 

PU 

PR 

0x25 % 


G 

PU 

PR 

0x26 & 


G 

PU 

PR 

0x27 1 


G 

PU 

PR 

0x28 ( 


G 

PU 

PR 

0x29 ) 


G 

PU 

PR 

0x2a * 


G 

PU 

PR 

0x2b + 


G 

PU 

PR 

0x2c , 


G 

PU 

PR 

0x2d - 


G 

PU 

PR 

0x2e . 


G 

PU 

PR 
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M- 

C\J 

X 

o 

/ 


G 

PU 

PR 


0x30 

0 AN 

D 

G 


PR 

X 

0x31 

1 AN 

D 

G 


PR 

X 

0x32 

2 AN 

D 

G 


PR 

X 

0x33 

3 AN 

D 

G 


PR 

X 

0x34 

4 AN 

D 

G 


PR 

X 

0x35 

5 AN 

D 

G 


PR 

X 


****************************************************************************/ 


“i swal num to i swxdi gi t — Test Wide Integer Value” on page 360 
“i swctype — Test for Character Property” on page 365 
“<wchar.h>” on page 821 
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wcwidth — Determine Display Width of Wide Character 

Format #include <wchar.h> 

int wcwidth (const wint_t wc ); 

Description Language Level: XPG4 

wcwidth determines the number of printing positions that a graphic representation of 
wc occupies on a display device. Each of the printing wide characters occupies its 
own number of printing positions on a display device. The number is independent of 
its location on the device. 

The behavior of wcwidth is affected by the LC_CTYPE category. 


Return Value wcwidth returns the number of printing positions occupied by wc. If wc is a null 

wide character, wcwidth returns 0. If wc is not a printing wide character, wc returns 
- 1 . 

Note: Under VisualAge C++, the printing width is 0 for a null character, 1 for a 
single-byte character, and 2 for a double-byte character. 



This example determines the printing width for the wide character A. 

#include <stdio.h> 

#include <wchar.h> 

int main(void) 

{ 

wint_t wc = L'A' ; 


printf("%lc has a width of %d\n", wc, wcwidth(wc)); 
return 0; 


/**************************************************************************** 

The output should be similar to : 


A has a width of 1 


kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 



“wcswidth — Determine Display Width of Wide-Character String” on page 789 
“<wchar.h>” on page 821 


798 VisualAge C++ C Library Reference 



write 


write — Writes from Buffer to File 

Format linclude <io.h> 

int write(int handle, const void *buffer, unsigned int count); 

Description Language Level: XPG4, Extension 

write writes count bytes from buffer into the file associated with handle. The 
write operation begins at the current position of the file pointer associated with the 
given file. If the file is open for appending, the operation begins at the end of the 
file. After the write operation, the file pointer is increased by the number of bytes 
actually written. 

If the given file was opened in text mode, each line feed character is replaced with a 
carriage return/line feed pair in the output. The replacement does not affect the return 
value. 

Note: In earlier releases of C Set ++, write began with an underscore (_write). 
Because it is defined by the X/Open standard, the underscore has been removed. For 
compatibility, VisualAge C++ will map _write to write for you. 

Return Value wri te returns the number of bytes moved from the buffer to the file. The return 

value may be positive but less than count. A return value of -1 indicates an error, 
and errno is set to one of the following values: 

Value Meaning 

EBADF The file handle is not valid, or the file is not open for writing. 

ENOSPC No space is left on the device. 

EOS2ERR The call to the operating system was not successful. 

This example writes the contents of the character array buffer to the output file 
whose handle is fh. 

#inc1ude <io.h> 

#inc1ude <stdio.h> 

#inc1ude <stdlib.h> 

#i nc1ude <fcntl.h> 

#include <string.h> 
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#define FILENAME "write.dat" 

int main(void) 

{ 

int fh; 

char buffer[20]; 

memset(buffer, 'a', 20); /* initialize storage */ 

printf("\nCreating " FILENAME ".\n"); 
system("echo Sample Program > " FILENAME); 
if (-1 == (fh = open(FILENAME, 0_RDWR|0_APPEND))) { 
perror("Unable to open " FILENAME); 
return EXIT_FAILURE; 

} 

if (5 != write(fh, buffer, 5)) { 

perror("Unable to write to " FILENAME); 
close(fh); 

return EXIT_FAILURE; 

} 

printf("Successfully appended 5 characters.\n"); 
close(fh); 
return 0; 

/**************************************************************************** 
The program should create a file "write.dat" containing: 

Sample Program 
aaaaa 

The output should be: 

Creating write.dat. 

Successfully appended 5 characters. 

****************************************************************************/ 

} 



“creat — Create New File” on page 115 
“fread — Read Items” on page 261 
“fwri te — Write Items” on page 289 
“1 seek — Move File Pointer” on page 393 
“open — Open File” on page 447 
“read — Read Into Buffer” on page 482 
“_sopen — Open Shared File” on page 545 
“_tel 1 — Get Pointer Position” on page 655 
“<io.h>” on page 804 
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Include Files 


The include files provided with the runtime library contain macro and constant 
definitions, type definitions, and function declarations. Some functions require 
definitions and declarations from include files to work properly. The inclusion of 
files is optional, as long as the necessary statements from the files are coded directly 
into the source. 

Note: If you change the default calling convention (using one of the /M options), you 
must include the appropriate header files with the declarations of the library functions 
that you use. 

This section describes each include file, explains its contents, and lists the functions 
that are declared in the file. 


<assert.h> 

The <assert.h> include file defines the assert macro. You must include assert.h 
when you use assert. 

The definition of assert is in an fifndef preprocessor block. If you have not 
defined the identifier NDEBUG through a #define directive or on the compiler 
command line, the assert macro tests a given expression (the assertion). If the 
assertion is false, the system prints a message to stderr and an abort signal is raised 
for the program. 

If NDEBUG is defined, assert is defined to do nothing. You can suppress program 
assertions by defining NDEBUG. 


<builtin.h> 


The <bui 11in.h> include file declares the following built-in and intrinsic functions: 


al1 oca 

_facos 

fsincos 

_i npw 

_rotl 

clear87 

_fasin 

_fyl2x 

_i nterrupt 

_rotr 

control87 

_fcos 

_fyl2xpl 

_1rotl 

_srotl 

crotl 

_fcossin 

_f2xml 

_1rotr 

_srotr 

crotr 

_fpatan 

_getTIBvalue 

_outp 

_parmdwords 

disable 

_fptan 

_i np 

_outpd 

_status87 

enable 

_fsin 

_i npd 

_outpw 



© Copyright IBM Corp. 1992, 1995 
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_clear87, _control87, and _status87 are also defined in <float.h>. _alloca is 
also defined in “<stdlib.h>” on page 816 and “<malloc.h>” on page 810. The 
functions _inp, _inpd, _inpw, _outp, _outpd, and _outpw are also defined in 
<conio.h>. 

<builtin.h> also includes a declaration for the type size_t. 


<collate.h> 


The <collate.h> include file declares functions that retrieve information about the 
current locale's collating properties: 

cclass collequiv collorder collrange colltostr 

getmccoll getwmccoll ismccollel maxcoll strtocoll 


<conio.h> 


The <conio.h> include file defines the functions that involve screen and console input 
and output: 


_cgets 

_cscanf 

_i np 

_kbhit 

_outpw 

_cprintf 

_getch 

_i npd 

_outp 

_putch 

_cputs 

_getche 

_i npw 

_outpd 

_ungetch 


<ctype.h> 

The <ctype.h> include file defines functions used in character classification. The 
functions defined in <ctype.h> are: 


isalnum 

isdigit 

isprirt 

isupper 

toupper 

isalpha 

isgraph 

ispunct 

isxdigit 


iscntrl 

isiower 

isspace 

tolower 



In extended mode, <ctype.h> also includes definitions for the following 
VisualAge C++ extensions: 

isascii _iscsymf _toascii _tolower _toupper 

_iscsym 

In the VisualAge C++ compiler, the <ctype.h> functions are all implemented as 
macros. 
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<direct.h> 


The <direct.h> include file defines functions that control directories and drives. The 
functions defined in <direct.h> are: 

chdir _getcwd _getdrive mkdir rindir 

_chdrive _getdcwd 


<errno.h> 

The <errno.h> include file defines symbolic macro names, such as EDOM and 
ERANGE, for runtime errors, and a modifiable lvalue having type int called errno. 
It also defines the global variable _doserrno, which is determined by the OS/2 error 
code when an operating system error occurs. 

See the online User's Guide for a list of the runtime error messages and the errno 
values associated with each message. 

Note: If you are going to test the value of errno after library function calls, first set 
it to 0, because its value may not be reset during the call. 

The definitions of errno and _doserrno are also provided in <stdlib.h> on page 
816. 


<fcntl.h> 

The <fcntl .h> include file defines constants used by the open and _sopen functions. 
Definitions for these two functions are included in “<io.h>” on page 804. Additional 
definitions for _sopen are provided in “<share.h>” on page 814. 


<float.h> 

The <float.h> include file defines constants that specify the ranges of floating-point 
data types, for example, the maximum number of digits for objects of type doubl e or 
the minimum exponent for objects of type float. 

In extended mode, <float.h> also defines the macros that represent infinity and NaN 
(not-a-number) values, and defines the following functions that manipulate the 
floating-point control and status words, and for the constants that they use: 

_clear87 _control87 _fpreset _status87 
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<iconv.h> 

The <iconv.h> include file declares the iconv_open, iconv, and iconv_close 
functions to convert characters from one character set definition to another. The 
ICONV utility also uses these functions. 

iconv.h also declares the iconv_t type, which is a pointer to an object capable of 
storing the information about the opened converters used. 


<io.h> 


The <io.h> include file defines the following file handle and low-level input and 
output functions: 


access 

dup 

isatty 

remove 

tel 1 

chmod 

dup2 

lseek 

rename 

umask 

_chsize 

_eof 

open 

_setmode 

uni ink 

close 

_fi1 elength 

read 

_sopen 

wri te 


creat 

Two additional functions, fstat and stat, are defined in <sys\stat.h>. 

Constants required by the open and _sopen functions are provided in <fcntl ,h>. 
Additional constants used by _sopen are defined in <share,h>. 

The unlink function is also defined in <stdio,h>. 


<langinfo.h> 

The <langinfo.h> include file declares the nl_langinfo function. The include file 
also defines the macros that, in turn, define constants that are used to identify the 
information queried in the current locale, and the nl_item type, which is the type of 
the constants. The following macros are defined: 

ABDAY_1 Abbreviated first day of the week 

ABDAY_2 Abbreviated second day of the week 

ABDAY_3 Abbreviated third day of the week 

ABDAY_4 Abbreviated fourth day of the week 

ABDAY_5 Abbreviated fifth day of the week 

ABDAY_6 Abbreviated sixth day of the week 

ABDAY_7 Abbreviated seventh day of the week 

ABM0N_1 Abbreviated first month 

ABM0N_2 Abbreviated second month 

ABM0N_3 Abbreviated third month 

ABM0N_4 Abbreviated fourth month 

ABM0N_5 Abbreviated fifth month 
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ABM0N_6 

ABM0N_7 

ABM0N_8 

ABM0N_9 

ABMON_10 

ABM0N_11 

ABM0N_12 

AM_STR 

CODESET 

CRNCYSTR 

D_FMT 

D_T_FMT 

DAY_1 

DAY_2 

DAY_3 

DAY_4 

DAY_5 

DAY_6 

DAY_7 

M0N_1 

M0N_2 

M0N_3 

M0N_4 

M0N_5 

M0N_6 

M0N_7 

M0N_8 

M0N_9 

MON_10 

M0N_11 

M0N_12 

NOEXPR 

PM_STR 

RADIXCHAR 

T_FMT 

T_FMT_AMPM 

THOUSEP 

YESEXPR 


Abbreviated sixth month 
Abbreviated seventh month 
Abbreviated eighth month 
Abbreviated ninth month 
Abbreviated tenth month 
Abbreviated eleventh month 
Abbreviated twelfth month 
String for morning 

Current encoded character set of the process 

Currency symbol 

String for formatting date 

String for formatting date and time 

Name of the first day of the week 

Name of the second day of the week 

Name of the third day of the week 

Name of the fourth day of the week 

Name of the fifth day of the week 

Name of the sixth day of the week 

Name of the seventh day of the week 

Name of the first month 

Name of the second month 

Name of the third month 

Name of the fourth month 

Name of the fifth month 

Name of the sixth month 

Name of the seventh month 

Name of the eighth month 

Name of the ninth month 

Name of the tenth month 

Name of the eleventh month 

Name of the twelfth month 

Negative response expression 

String for afternoon 

Radix character 

String for formatting time 

String for morning or afternoon time format 

Separator for thousands 

Affirmative response expression 


For more information about the effect of locale, see “setlocale — Set Locale” on 
page 530, “<locale.h>” on page 806, individual functions, and the introduction to 
locale in the Programming Guide. 
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<lc_core.h> 

The <lc_core.h> include file declares the LOCALDEF utility. Do not include it in 
your source code. 

The LOCALDEF utility is described in the User's Guide. For more information about 
locales in general, see the introduction to locale in the Programming Guide. 


<limits.h> 

The <1 imits.h> include file defines constants that specify the ranges of integer and 
character data types, such as the maximum value for an object of type char. 


<localdef.h> 

The <localdef.h> include file declares the LOCALDEF utility. Do not include it in 
your source code. 

The LOCALDEF utility is described in the User's Guide. For more information about 
locales in general, see the introduction to locale in the Programming Guide. 


<locale.h> 

The <locale.h> include file declares the localdtconv, localeconv, and setlocale 
library functions, which are useful for changing the C locale when you are creating 
applications for international users. <locale.h> also declares the lconv structure. 

The table below shows the elements of the 1 conv structure as well as the defaults for 
the C locale. 


Table 8 (Page 1 of 3). 

Elements of the lconv Structure 

Element 

Purpose of Element Default 

char *decimal_point 

Decimal-point character used to format 
nonmonetary quantities. 

char *thousands_sep 

Character used to separate groups of digits "" 

to the left of the decimal-point character in 
formatted nonmonetary quantities. 
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Table 8 (Page 2 of 3). Elements of the Iconv Structure 

Element 

Purpose of Element 

Default 

char *grouping 

String indicating the size of each group of 
digits in formatted nonmonetary quantities. 
The value of each character in the string 
determines the number of digits in a group. 

A value of CHAR MAX indicates that there are 
no further groupings. 0 indicates that the 
previous element is to be used for the 
remainder of the digits. 

II II 

char *int_curr_symbol 

International currency symbol for the 
current locale. The first three characters 
contain the alphabetic international 
currency symbol. The fourth character 
(usually a space) is the character used to 
separate the international currency symbol 
from the monetary quantity. 

II II 

char *currency_symbol 

Local currency symbol of the current 
locale. 

II II 

char *mon_decimal_point 

Decimal-point character used to format 
monetary quantities. 

II II 

char *mon_thousands_sep 

Separator for digits in formatted monetary 
quantities. 

II II 

char *mon_grouping 

String indicating the size of each group of 
digits in formatted monetary quantities. 

The value of each character in the string 
determines the number of digits in a group. 

A value of CHAR MAX indicates that there are 
no further groupings. 0 indicates that the 
previous element is to be used for the 
remainder of the digits. 

II II 

char *positive_sign 

String indicating the positive sign used in 
monetary quantities. 

II II 

char *negative_sign 

String indicating the negative sign used in 
monetary quantities. 

II II 

char int_frac_digits 

The number of displayed digits to the right 
of the decimal place for internationally 
formatted monetary quantities. 

UCHAR_MAX 

char frac_digits 

Number of digits to the right of the 
decimal place in monetary quantities. 

UCHAR_MAX 
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Table 8 (Page 3 of 3). Elements of the Iconv Structure 

Element 

Purpose of Element 

Default 

char 

P_ cs _P recedes 

1 if the currency_symbol precedes the value 
for a nonnegative formatted monetary 
quantity; 0 if it does not. 

UCHAR_ 

MAX 

char 

P_ se P_by_space 

1 if the currency_symbol is separated by a 
space from the value of a nonnegative 
formatted monetary quantity; 0 if it does 
not; 2 if a space separates the symbol and 
the sign string—if adjacent. 

UCHAR_ 

MAX 

char 

n_cs_prec e des 

1 if the currency_symbol precedes the value 
for a negative formatted monetary quantity; 

0 if it does not. 

UCHAR_ 

MAX 

char 

n_sep_by_space 

1 if the currency_symbol is separated by a 
space from the value of a negative 
formatted monetary quantity; 0 if it does 
not; 2 if a space separates the symbol and 
the sign string—if adjacent. 

UCHAR_ 

MAX 

char 

P_ sl 9 n _P osn 

Value indicating the position of the 
positive_sign for a nonnegative formatted 
monetary quantity. 

UCHAR_ 

MAX 

char 

n _ sl 9 n _P osn 

Value indicating the position of the 
negative_sign for a negative formatted 
monetary quantity. 

UCHAR_ 

MAX 

char 

*1eft_parenthesis 

Negative-valued monetary symbol. 

II II 


char 

*right_parenthesis 

Negative-valued monetary symbol. 

II II 


char 

*debit_sign 

Debit_sign characters. 

II II 


char 

*credit_sign 

Credit_sign characters. 

II II 
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<locale.h> declares the dtconv structure: 
struct dtconv { 


char 

*abbrev_month_names[12]; 

/* 

Abbreviated month names 

*/ 

char 

*month_names[12]; 

/* 

full month names 

*/ 

char 

*abbrev_day_names[7]; 

/* 

Abbreviated day names 

*/ 

char 

*day_names[7]; 

/* 

full day names 

*/ 

char 

*date_time format; 

/* 

date and time format 

*/ 

char 

*date_format; 

/* 

date format 

*/ 

char 

*time format; 

/* 

time format 

*/ 

char 

*am string; 

/* 

AM string 

*/ 

char 

*pm string; 

/* 

PM string 

*/ 

char 

*time_format_ampm; 

/* 

long date format 

*/ 


h 


The information in each field is equivalent to calling nl_langinfo with these 
keywords: 


Keyword 

abmon 

mon 

abday 

day 

d_t_fmt 

d_fmt 

t_fmt 

ampni 

ampni 

t_fmtampm 


Element 

abbrev_month_names 

month_names 

abbrev_day_names 

day_names 

date_time_format 

date_format 

time_format 

am_string 

pm_string 

time_format_ampm 


<locale.h> also contains definitions for the following macros: 


LC_ALL 

LC_COLLATE 

LC_CTYPE 

LC_MESSAGES 

LC_TOD 


LC_NUMERIC 
LC_TIME 
LC_SYNTAX 
LC_MONET ARY 
NULL 


It also contains definitions for the LC_C_* macros, which are provided for 
compatibility with C Set ++ V2.0. 

The aspects of a program related to national language, or to cultural characteristics 
(such as time zone, currency symbols, and sorting order of characters), can be 
customized at run time using different locales, to suit users' requirements at those 
locales. The methods for doing so are discussed in the internationalization chapters 
of the Programming Guide. 
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<malloc.h> 


The <malloc.h> include file defines the following memory allocation functions: 


_al1 oca 
cal 1oc 

_debug_cal1oc 
_debug_free 
_debug_mal1oc 
_debug_heapmin 
_debug_real1oc 


debug_tcal1oc 
debug_tfree 
debug_theapmin 
debug_tmal1oc 
debug_treal1oc 
dump_al1ocated 
dump_al1ocated_delta 


free 

_heap_check 
mal1oc 
jnheap 
_msize 
real 1oc 
teal 1oc 


tdump_al1ocated 
tdump_al1ocated_delta 
tfree 

theap_check 
theapmin 
tmal1oc 
treal1oc 


It also includes a definition for the type size_t. 

calloc, free, malloc, and realloc are also defined in <stdlib.h>, as are _alloca 
and _heapmi n. 


The tiled and debug versions of the memory management functions are also defined 
in <stdlib.h>. Heap-specific versions of the memory management functions are 
defined in <umal 1 oc. h>. 

Note: To use the tiled functions, you must compile with the tiled memory (/Gt) 
option. To use the debug functions, you must compile with the debug memory (/Tm) 
option. To use the tiled debug functions, you must compile with both the tiled 
memory and debug memory options (/Gt /Tm). See “Differentiating between Memory 
Management Functions” on page 28 for more information about the different types of 
memory management functions. 


<mal loc.h> also defines a number of far and near pointer macros to the 
corresponding standard library function. These macros are: 


fcal1oc 
fheapmin 
freal1oc 
nfree 
nmal1oc 


ffree 
fmal1oc 
ncal1oc 
nheapmin 
nreal1oc 


These macros are also defined in <stdlib.h>. 
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<math.h> 


The <math.h> include file declares all the floating-point math functions: 


acos 

cos 

fl oor 

log 

sqrt 

asi n 

cosh 

fmod 

loglO 

tan 

atan 

erf 

frexp 

modf 

tanh 

atan2 

erfc 

gamma 

pow 


Bessel 

exp 

hypot 

sin 


cei 1 

fabs 

ldexp 

si nh 



Note: The Bessel functions are a group of functions named _j0, _jl, _jn, _y0, _yl, 
and _yn. 

<math.h> also includes definitions for the following VisualAge C++ extensions: 

_atold 

_cabs 

_matherr 

The _atold function is also defined in “<stdlib.h>” on page 816. 

<math.h> defines the macros HUGE, _LHUGE, HUGE_VAL, and _LHUGE_VAL, which expand 
to a positive doubl e expression or to infinity. 

You can define a macro _FP_INLINE to inline the functions sin, cos, tan, atan, acos 
and asin. If you use _FP_INLINE to inline the functions, you cannot use the functions 
defined in <complex.h>, or an error message is generated. 

For all mathematical functions, a domain error occurs when an input argument is 
outside the range of values allowed for that function. In the event of a domain error, 
errno is set to the value of EDOM. 

A range error occurs if the result of the function cannot be represented in a doubl e 
value. If the magnitude of the result is too large (overflow), the function returns the 
positive or negative value of the macro HUGE_VAL, and sets errno to ERANGE. If 
the result is too small (underflow), the function returns zero. 


<memory.h> 

The <memory.h> include file defines the following buffer manipulation functions: 


memccpy 
memcmp 
memicmp 
memset 


memchr 

memcpy 

memmove 


Chapter 4. Include Files 811 



Include Files 


Definitions of these functions are also provided in“<string.h>” on page 818 . 

The <memory.h> include file also defines a number of far and near pointer macros to 
the corresponding standard library function. These macros are: 

_fmemccpy _fmemchr 

_fmemcmp _fmemcpy 

cmp _fmemset 

These macros are also defined in <string.h>. 


<monetary.h> 

The <monetary.h> include file declares the strfmon function. 

For more information about the effect of locale, see “setlocale — Set Locale” on 
page 530, “<locale.h>” on page 806, individual functions, and the introduction to 
locale in the Programming Guide. 


<nl_types.h> 

The <nl_types.h> include file defines the nl_item type for the nl_langinfo 
function. 

For more information about the effect of locale, see “setlocale — Set Locale” on 
page 530, “<locale.h>” on page 806, individual functions, and the introduction to 
locale in the Programming Guide. 


<process.h> 


The <process.h> include file defines the process control functions: 


abort 

_beginthread 
_cwait 
_endthread 
execl 


execle 
execlp 
_execlpe 
execv 
execve 


execvp 
_execvpe 
exi t 
_exi t 
getpid 


spawnl 
spawnle 
spawnlp 
spawnlpe 
spawnv 


_spawnve 

_spawnvp 

_spawnvpe 

system 


The definitions of _beginthread, _endthread, abort, exit, and system are also 
provided in <stdlib.h>. 
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<regex.h> 

The <regex.h> include file declares the type size_t and defines the following regular 
expression functions: 

regcomp regerror 

regexec regfree 

<regex.h> also declares the regex_t type, which is capable of storing a compiled 
regular expression, and the following macros: 

REG_EXTENDED 

REGJCASE 

REG_NEWLINE 

REG_NOSUB Values of the cflags parameter of the regcomp 
function 


REG_NOTBOL 

REG_NOTEOL Values of the eflags parameter of the regexec 
function 

REG_* Values of the errcode parameter of the regerror function 


<search.h> 

The <search.h> include file defines the following search functions: 

bsearch lfind 

1 search qsort 

It also defines the type size_t. 

Definitions for bsearch and qsort are also provided in <stdlib.h>. 


<setjmp.h> 

The <setjmp.h> include file declares the setjmp macro and longjmp function. It also 
defines a buffer type, jmp_buf, that the setjmp macro and longjmp function use to 
save and restore the program state. 
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<share.h> 

The <share.h> include file defines constants used by the following functions: 

creat fdopen 

open _sopen 

The definitions for the above functions are also included in <io.h>. Additional 
constants for open and _sopen are provided in <fcntl .h>. 


<signal.h> 


The <signal .h> include file defines the values for signals and declares the signal 
and raise functions. 


<signal .h> also defines the following macros: 

SIGABRT SIG_ERR SIGILL SIGSEGV SIGUSR1 

SIGBREAK SIGFPE SIGINT SIGTERM SIGUSR2 

SIG_DFL SIG_IGN SIGUSR3 

<signal .h> also defines the type sig_atomic_t. 


<stdarg.h> 


The <stdarg.h> include file defines macros that allow you access to arguments in 
functions with variable-length argument lists: va_arg, va_start, and va_end. 
<stdarg.h> also defines the type va_list. 


<stddef.h> 

The <stddef.h> include file defines the commonly used pointers, variables, and types, 
from typedef statements, as listed below: 

ptrdiff_t typedef for the type of the difference of two pointers 

size_t typedef for the type of the value returned by sizeof 

wchar_t typedef for a wide character constant. 

<stddef.h> also defines the macros NULL and offsetof. NULL is a pointer that is 
guaranteed not to point to a data object. NULL is also defined in <locale.h>. The 
offsetof macro expands to the number of bytes between a structure member and the 
start of the structure. The offsetof macro has the form: 

offsetof (structure_type, member) 
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In extended mode, <stddef.h> also contains definitions of the global variables errno 
and _threadid. errno is also defined in <stdlib.h> for extended mode, and in 
<errno.h> in ANSI and SAA modes. 

<stdio.h> 

The <stdio.h> include file defines constants, macros, and types, and declares stream 
input and output functions. The stream I/O functions are: 


clearerr 

fprintf 

fwrite 

remove 

tmpnam 

fclose 

fputc 

getc 

rename 

ungetc 

feof 

fputs 

getchar 

rewind 

vfprintf 

terror 

tread 

gets 

scant 

vprintf 

fflush 

freopen 

perror 

setbuf 

vsprintf 

fgetc 

fscanf 

printf 

setvbuf 


fgetpos 

fseek 

putc 

sprintf 


fgets 

fsetpos 

putchar 

sscanf 


fopen 

ftell 

puts 

tmpfi1e 



In extended mode, <stdio.h> also defines the following extensions: 

_fcloseall _fputchar _set_crt_msg_handl e 

fdopen _flushal 1 tempnam 

_fgetchar _rmtmp unlink 

fi1eno 

<stdio.h> also defines the macros listed below. You can use these constants in your 
programs, but you should not alter their values. 

BUFSIZ Specifies the buffer size to be used by the setbuf library function 

when you are allocating buffers for stream I/O. This value 
establishes the size of system-allocated buffers and is used with 
setbuf. 

EOF The value returned by an I/O function when the end of the file (or in 

some cases, an error) is found. 

F0PEN_MAX The number of files that can be opened simultaneously. 

FILENAME_MAX The longest file name supported. If there is no reasonable limit, 
FILENAME_MAX will be the recommended size. 

L_tmpnam The size of the longest temporary name that can be generated by the 

tmpnam function. 

P_tmpdir Indicates the default directory to be used by the tempnam function. 

TMP_MAX The minimum number of unique file names that can be generated by 

the tmpnam function. 
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NULL A pointer guaranteed not to point to a data object. NULL is also 

defined in <locale.h>. 

The FILE structure type is defined in <stdio.h>. Stream I/O functions use a pointer 
to the FILE type to get access to a given stream. The system uses the information in 
the FILE structure to maintain the stream. 

The C standard streams stdin. stdout, and stderr are also defined in <stdio.h>. 

The macros SEEK_CUR, SEEK_END, and SEEK_SET expand to integral constant expressions 
and can be used as the third argument to fseek. 

The macros _I0FBF, _I0LBF, and _I0NBF expand to integral constant expressions with 
distinct values suitable for use as the third argument to the setvbuf function. 

The type fpos_t is defined in <stdio.h> for use with fgetpos and fsetpos. 


<stdlib.h> 


The <stdlib.h> include file declares the following functions: 


abort 

bsearch 

1 abs 

qsort 

strtoul 

abs 

cal 1oc 

1 di v 

rand 

system 

atexit 

div 

mal1oc 

real 1oc 

wctomb 

atof 

exit 

mbl en 

srand 

wcstombs 

atoi 

free 

mbstowcs 

strtod 


atol 

getenv 

mbtowc 

strtol 



In extended mode, <stdlib.h> also defines the following standard extensions: 


al1 oca 
atol d 

beginthread 

crotl 

crotr 

debug_cal1oc 
debug_free 
debug_heapmin 
debug jtial 1 oc 
debug_real1oc 
debug_tcal1oc 
debug_tfree 
debug_theapmin 
debug_tmal1oc 


debug_treal1oc 
dump_al1ocated 
dump_al1ocated_delta 
ecvt 

endthread 
exi t 
fcvt 
freemod 
ful1 path 
gcvt 
heapmin 
heap_check 
i toa 
1oadmod 


_1rotl 
_1rotr 
_1 toa 
_makepath 
max 
mi n 

_msize 
_onexit 

_parmdwords 

putenv 
_rotl 
_rotr 
_searchenv 
_splitpath 


_srotl 
_srotr 
strtold 
swab 

_tcal1oc 

_tdump_al1ocated 
_tdump_al1ocated_delta 
_tfree 

_theap_check 
_theapmin 
_threadstore 
_tmal1oc 
_treal1oc 
ul toa 
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Notes: 

1. To use the debug memory management functions (_debug_cal loc, 

_dump_allocated, and so on), you must compile with the debug memory (/Tm) 
option. 

2. To use the tiled memory management functions (_tcal loc and so on) you must 
compile with the tiled memory (/Gt) option. 

3. To use tiled debug functions (_debug_tcal 1 oc, _tdump_allocated, and so on), 
you must compile with the debug memory and tiled memory options (/Tm /Gt). 

For a description of how these functions differ, see “Differentiating between Memory 
Management Functions” on page 28. For more information about the memory 
management functions, see Memory Management in the Programming Guide. 

<stdlib.h> also contains definitions for the following macros: 


NULL 


EXIT_SUCCESS 
EXIT_FAILURE 
RAND_MAX 

MB_CUR_MAX 


The NULL pointer value. The value of NULL is 0 when in 
extended mode; otherwise, its value is ((void*)0). NULL is 
also defined in <locale.h>. 

Expands to 0; used by the atexi t function. 

Expands to 8; used by the atexi t function. 

Expands to an integer representing the largest number that the 
rand function can return. 

Expands to an integral expression representing the maximum 
number of bytes in a multibyte character for the current 
locale. 


For more information on NULL and the types size_t and wchar_t, see “<stddef.h>” 
on page 814. 

In extended mode, <stdlib.h> also defines the following global variables: 

doserrno environ 

errno onexitt 

_osmajor _osminor 

_osmode 

The variable errno is also defined in <stddef.h>. The variable _doserrno and the 
SAA definition of errno are provided in <errno.h>. 
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<stdlib.h> also defines the following far and near pointer macros to the 
corresponding standard library function: 


fcal1oc 
fmal1oc 
freal1oc 
nfree 
nheapmin 


ffree 
f heapin' n 
ncal1oc 
nmal1oc 
nreal1oc 


These macros are also defined in <malloc.h>. 


<string.h> 


The <stri ng. 

, h> include file declares the string 

manipulation functions: 


memchr 

strcat 

strcspn 

strncmp 

strspn 

memcmp 

strchr 

strerror 

strncpy 

strstr 

memcpy 

strcmp 

strlen 

strpbrk 

strtok 

memmove 

strcol1 

strncat 

strrchr 

strxfrm 

memset 

strcpy 




In extended mode, <string.h> also defines the 

following standard extensions: 

memccpy 

strdup 

strlwr 

strnset 

strset 

memicmp 

_strerror 

stmi cmp 

strrev 

strupr 

strcmpi 

stricmp 





The memxxxx functions are also included in “<memory.h>” on page 811. 

<string.h> also defines the macro NULL and the type size_t. 

For more information on NULL and the type size_t, see “<stddef.h>” on page 814. 
NULL is also defined in <1ocale.h>. 


string.h also defines the following far and near pointer macros to the 
corresponding standard library function: 


_fmemccpy 

fmemset 

_fstrdup 

_fstrncpy 

fstrset 

fmemchr 

fstrcat 

fstricmp 

_fstrnicmp 

fstrspn 

_fmemcmp 

_fstrchr 

fstrlen 

_fstrnset 

fstrstr 

fmemcpy 

_fstrcmp 

fstrlwr 

_fstrpbrk 

fstrtok 

fmemicmp 

_fstrcpy 

fstrncat 

_fstrrchr 

fstrupr 

fmemmove 

_fstrcspn 

_fstrncmp 

_fstrrev 

nstrdup 


These macros are also defined in <memory.h>. 
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<sys\stat.h> 

The <sys\stat.h> include file defines the low-level input/output functions fstat and 
stat. It also defines the structure stat and the following types: 

dev_t ino_t 

off_t time_t 

These types are also defined in <sys\types.h>. Other low-level I/O functions are 
defined in <io.h>. 


<sys\timeb.h> 

The <sys\timeb.h> include file defines the _ftime function and also defines the type 
time t and the structure timeb. 


<sys\types.h> 

The <sys\types.h> include file defines the following types: 

ino_t time_t 

dev_t off_t 

These types are also defined in <sys\stat.h>. 


<sys\utime.h> 

The <sys\utime. h> include file defines the utime function, the structure utimbuf, and 
the type time_t. 


<time.h> 


The <time.h> include file declares the time and date functions: 

asctime ctime gmtime mktime time 

clock difftime localtime strftime 

In extended mode, <time.h> also defines the standard extensions _strdate, _strtime, 
and tzset. 
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<time.h> also provides: 

• A structure tm containing the components of a calendar time. See “gmtime — 
Convert Time” on page 321 for a list of the members of the tm structure. 

• A macro CLOCKS_PER_SEC equal to the number per second of the value returned by 
the clock function. 

• Types clock_t, time_t, and size_t. 

• The NULL pointer value. 

For more information on NULL and the type size_t, see “<stddef.h>” on page 814. 
<time.h> also defines the global variables _daylight, _timezone, and _tzname. 


<umalloc.h> 


The <umalloc.h> include 

file defines the 

memory allocation functions that are 

heap-specific: 




_debug_ucal1oc 

_ucal1oc 

_udump_al1ocated 

_uheapset 

_debug_uheapmin 

_uclose 

_udump_al1ocated_delta 

_uheap_walk 

_debug_umal1oc 

_ucreate 

_uheapchk 

_umal1oc 

jnheap 

_udefault 

_uheap_check 

_uopen 

_uaddmem 

_udestroy 

_uheapmin 



<umalloc.h> also defines macros used by the heap-specific functions. 


Definitions for the non-heap-specific memory management functions are located in 
<stdlib.h> and in <malloc.h>. 

Note: To use the debug versions of memory management functions, specify the 
debug memory (/Tm) compiler option. 
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<variant.h> 


The <variant.h> include file declares the getsyntx function and for the struct 
variant type: 


struct variant { 

char *codeset; 

/* 

code set 

of 

the current locale */ 

char 

backslash; 

/* 

encoding 

of 

\ 

*/ 

char 

right_bracket; 

/* 

encoding 

of 

] 

*/ 

char 

left_bracket; 

/* 

encoding 

of 

[ 

*/ 

char 

right_brace; 

/* 

encoding 

of 

} 

*/ 

char 

1eft_brace; 

/* 

encoding 

of 

{ 

*/ 

char 

circumflex; 

/* 

encoding 

of 

/\ 

*/ 

char 

tilde; 

/* 

encoding 

of 

~ 

*/ 

char 

exclamationjnark; 

/* 

encoding 

of 

! 

*/ 

char 

number_sign; 

/* 

encoding 

of 

# 

*/ 

char 

vertical_1ine; 

/* 

encoding 

of 

l 

*/ 

char 

dollar_sign; 

/* 

encoding 

of 

$ 

*/ 

char 

commercial_at; 

/* 

encoding 

of 


*/ 

char 

grave_accent; 

/* 

encoding 

of 

*■ 

*/ 


} 


For more information about the effect of locale, see “setlocale — Set Locale” on 
page 530, “<locale.h>” on page 806, individual functions, and the introduction to 
locale in the Programming Guide. 


<wchar.h> 


The <wchar.h> include file declares the supported subset of the ISO/C Multibyte 
Support extensions defined in ISO/IEC 9899:1990/Amendment 1:1993(E) extensions. 
The following functions are declared in <wchar.h>: 


fgetwc 

putwchar 

wcscpy 

wcsspn 

fgetws 

swprintf 

wcscspn 

wcsstr 

fputwc 

swscanf 

wcsftime 

wcstod 

fputws 

ungetwc 

wcslen 

wcstok 

getwc 

vswprintf 

wcsncat 

wcstol 

getwchar 

wcrtomb 

wcsncmp 

wcstoul 

mbrl en 

wcscat 

wcsncpy 

wcswidth 

mbrtowc 

wcschr 

wcspbrk 

wcsxfrm 

mbsrtowcs 

wcscmp 

wcsrchr 

wctob 

putwc 

wcscol1 

wcsrtombs 

wcwidth 


You do not need to include <stdio.h> and <stdarg.h> to use this include file. 
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<wchar.h> also defines the following types and constants: 


mbstate_t 

sizet 
wchar_t 
wint t 


FILE 


Conversion state information needed when converting between 
sequences of multibyte characters and wide characters. 

typedef for the type of the value returned by sizeof. 

typedef for a wide character constant. 

An integral type unchanged by integral promotions, that can hold any 
value corresponding to members of the extended character set, as well 
as WEOF (see below). 

The FILE structure type is defined in <stdio.h>. Stream functions 
use a pointer to the FILE type to get access to a given stream. The 
system uses the information in the FILE structure to maintain the 
stream. The C standard streams stdin, stdout, and stderr are also 
defined in <stdio.h>. 


va_list This type is also defined in <stdio.h>. 

NULL A pointer that never points to a data object. 

WEOL Expands to a constant expression of type wint_t, whose value does 

not correspond to any member of the extended character set. It 
indicates EOF. 


You can perform wide character input/output on the streams described in the ISO/IEC 
9899:1990 standard, subclause 7.9.2. This standard expands the definition of a stream 
to include an orientation for both text and binary streams. After you have associated 
a stream with an external file, but before you have performed any operations on it, 
the stream does not have any orientation. Once you apply a wide character input or 
output function to a stream that does not have orientation, the stream becomes 
wide-oriented. Similarly, once you apply a byte input or output function to a stream 
without orientation, the stream becomes byte-oriented. 

After you establish a stream's orientation, the only way to change it is to make a 
successful call to the freopen function, which removes a stream's orientation. 

For more information about the effect of locale, see “setlocale — Set Locale” on 
page 530, “<locale.h>” on page 806, individual functions, and the introduction to 
locale in the Programming Guide. 
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<wcstr.h> 


The wcstr.h include file declares the multibyte functions: 


wcscat 

wcscpy 

wcsncat 

wcspbrk 

wcswcs 

wcschr 

wcscspn 

wcsncmp 

wcsspn 


wcscmp 

wcslen 

wcsncpy 

wcsrchr 



wcstr.h also defines the types size_t, NULL, and wchar_t. 


<wctype.h> 

The <wctype.h> file declares functions used to classify wide characters: 


swalnum 

iswctype 

iswprint 

i swxdigit 

swalpha 

i swdigit 

iswpunct 

fowlower 

swblank 

i swgraph 

iswspace 

towupper 

swcntrl 

swctype 

i swlower 

iswupper 

wctype 


wctype.h also defines the types wint_t and wctype_t, and the macro WEOF, which 
expands to a constant expression of type wint_t whose value does not correspond to 
any member of the extended character set and indicates EOF. 
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VisualAge C++ Functions and Macros 

This appendix lists the C functions and macros supported by VisualAge C++. It also 
includes a list of the predefined macros that are reserved for use by VisualAge C++ 
product. 


Functions and Macros 


This section lists all the C functions and macros supported by VisualAge C++, and 
classifies each according to the following table: 


ANSI/ISO Defined in the ANSI/ISO 9899-1990[ 1992] C standard. 
ANSI/ISO 93 Defined in the ISO/IEC 9899:1990/Amendment 1:1993(E). 


POSIX 

XPG4 

SAA 


Defined in the ISO/IEC 9945-1:1990/IEEE POSIX 1003.1-1990 
standard. 

Defined in the X/Open Common Applications Environment 
Specification, System Interfaces and Headers, Issue 4. 


Defined in the SAA Level 2 C standard. 

Extension Extension to existing standards, specific to the VisualAge C++ compiler. 
Subsystem Included in the subsystem libraries. 


If you are writing code to be ported to other standards-conforming systems, you can 
use the following table to find out which VisualAge C++ functions are portable. You 
can also set the language level of your source code to ensure only portable functions 
are used: 

• To allow only functions defined by ANSI/ISO, set the language level to ANSI. 

• To allow SAA functions as well as ANSI/ISO functions, set the language level to 
SAA or SAAL2. 

• To allow all VisualAge C++ functions, set the language level to Extended (this is 
the default). 


Where a function is classified under a language standard and also as an extension, the 
function conforms to the standard indicated but has additional implementation-defined 
features. Such a function is considered to be an extension. If you set the language 
level to ANSI or SAA, you can still use the function but the additional features will 
not be available. 
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Predefined Macros 

The macros identified in this section are provided to allow customers to write 
programs that use VisualAge C++ services. Only those macros identified in this 
section should be used to request or receive VisualAge C++ services. 

VisualAge C++ compiler provides both the SAA predefined macros and a number of 
macros specific to VisualAge C++ product. 


SAA Macros 

Macro 

_LINE_ 

_FILE_ 

_DATE_ 

_TIME_ 

_TIMESTAMP_ 

_STDC_ 

ANSI 


SAA 


SAA_L2 


EXTENDED 


Description 

Represents the current source line number. 

Indicates the name of the source file 

Indicates the date when the source file was compiled. 

Indicates the time when the source file was compiled. 

Indicates the date and time when the file was last modified. 

Set to the integer 1. Indicates the compiler complies with ANSI 
C standards. This macro is defined for C programs only. 
Indicates only language constructs that conform to ANSI C 
standards are allowed. Defined using the #pragma 
langlvl (ansi) directive or /Sa compiler option. 

Indicates only language constructs that conform to the most 
recent level of SAA C standards are allowed. Defined using the 
#pragma langlvl (saa) directive or /S2 compiler option. This 
macro is defined for C programs only. 

Indicates only language constructs that conform to SAA Level 2 
C standards are allowed.. Defined using the fpragma 
langlvl (saal2) directive or /S2 compiler option. This macro 
is defined for C programs only. 

Indicates additional language constructs defined by the 
implementation are allowed. Under the VisualAge C++ 
compiler, all language constructs are allowed. Defined using 
the fpragma langlvl (extended) directive or /Se compiler 
option. 


VisualAge C++ Macros 

Macro Description 

_CHAR_UNSIGNED Indicates default character type is unsigned. Defined when the 
fpragma chars (unsigned) directive is in effect, or when the 
/J+ compiler option is set. 

_CHAR_SIGNED Indicates default character type is signed. Defined when the 

fpragma chars (signed) directive is in effect, or when the /J- 
compiler option is set. 
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COMPAT 


cpluspl US 


_DBCS_ 

_DDNAMES_ 

_DEBUG_ALLOC_ 

_DLL_ 

FP_IN LIN E_ 

_FUNCTION_ 

_HHW_INTEL_ 

_H0S_0S2_ 

_I BMC_ 

_IBMCPP_ 

_IMPORT LIB_ 

M_I386 
_MU LTI_ 

_NO_DEFAULT_LIBS 

_OS2_ 

_SOM_ENABLED_ 

_SPC_ 

TEMPINC 


THW_INTEL 

T0S_0S2_ 

TILED_ 

32BIT 


Indicates language constructs compatible with earlier versions of 
the C++ language are allowed. Defined using the fpragma 
langlvl (compat) directive or /Sc compiler option. This macro 
is defined for C++ programs only. 

Set to the integer 1. Indicates the product is a C++ compiler. 
This macro is defined for C++ programs only. 

Indicates DBCS support is enabled. Defined using the /Sn 
compiler option. 

Indicates ddnames are supported. Defined using the /Sh 
compiler option. 

Maps memory management functions to their debug versions. 
Defined using the /Tm compiler option. 

Indicates code for a DLL is being compiled. Defined using the 
/Ge- compiler option. 

Inlines the trigonometric functions (cos, sin, and so on). 
Indicates the name of the function currently being compiled. 

For C++ programs, expands to the actual function prototype. 
Indicates that the host hardware is an Intel** processor. 

Indicates that the host operating system is OS/2. 

Indicates the version number of the VisualAge C compiler. 
Indicates the version number of the VisualAge C++ compiler. 
Indicates that dynamic linking is used. Defined using the /Gd 
option. 

Indicates code is being compiled for a 386 chip or higher. 
Indicates multithread code is being generated. Defined using 
the /Gm compiler option. 

Indicates that information about default libraries will not be 
included in object files. Defined using the /Gd option. 

Set to the integer 1. Indicates the product is an OS/2 compiler. 
Indicates that native SOM is supported. 

Indicates the subsystem libraries are being used. Defined using 
the /Rn compiler option. 

Indicates the template-implementation file method of resolving 
template functions is being used. Defined using the /Ft 
compiler option. 

Indicates that the target hardware is an Intel processor. 

Indicates that the target operating system is OS/2. 

Indicates tiled memory is being used. Defined using the /Gt 
compiler option. 

Set to the integer 1. Indicates the product is a 32-bit compiler. 


850 VisualAge C++ C Library Reference 



Predefined Macros 


The value of the _I BMC_and_IBMCPP_macros is 300. One of these two macros 

is always defined: when you compile C++ code, _IBMCPP_is defined; when you 

compile C code, I BMC is defined. The macros 0S2 , _M_I386, and 32BIT 

are always defined also. The remaining macros, with the exception of_FUNCTION_, 

are defined when the corresponding #pragma directive or compiler option is used. 
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Glossary 


This glossary defines terms and abbreviations that 
are used in this book. Included are terms and 
definitions from the following sources: 

• American National Standard Dictionary for 
Information Systems, ANSI X3.172-1990, 
copyright 1990 by the American National 
Standards Institute (ANSI). Copies may be 
purchased from the American National 
Standards Institute, 1430 Broadway, New 
York, New York 10018. Such definitions are 
indicated by the symbol ANSI after the 
definition. 

• IBM Dictionary of Computing, SC20-1699. 
These definitions are indicated by the 
registered trademark IBM after the definition. 

• X/Open CAE Specification. Commands and 
Utilities, Issue 4. July, 1992. These 
definitions are indicated by the symbol 
X/Open after the definition. 


• ISO/IEC 9945-1:1990/IEEE POSIX 
1003.1-1990. These definitions are indicated 
by the symbol ISO.l after the definition. 

• The Information Technology Vocabulary, 
developed by Subcommittee 1, Joint 
Technical Committee 1, of the International 
Organization for Standardization and the 
International Electrotechnical Commission 
(ISO/IEC JTC1/SC1). Definitions of 
published parts of this vocabulary are 
identified by the symbol ISO-JTC1 after the 
definition; definitions taken from draft 
international standards, committee drafts, and 
working papers being developed by ISO/IEC 
JTC1/SC1 are identified by the symbol ISO 
Draft after the definition, indicating that final 
agreement has not yet been reached among 
the participating National Bodies of SCI. 


A 

abstraction (data). A data type with a private 
representation and a public set of operations. The 
C++ language uses the concept of classes to 
implement data abstraction. 

access. An attribute that determines whether or 
not a class member is accessible in an expression 
or declaration. 

access mode. (1) A technique that is used to 
obtain a particular logical record from, or to place 
a particular logical record into, a file assigned to 
a mass storage device. ANSI. (2) The manner in 
which files are referred to by a computer. Access 
can be sequential (records are referred to one 
after another in the order in which they appear on 
the file), access can be random (the individual 
records can be referred to in a nonsequential 
manner), or access can be dynamic (records can 
be accessed sequentially or randomly, depending 
on the form of the input/output request). IBM. 

(3) A particular form of access permitted to a 
file. X/Open. 


alignment. The storing of data in relation to 
certain machine-dependent boundaries. IBM. 

American National Standards Institute. See 

ANSI. 

ANSI (American National Standards 
Institute). An organization consisting of 
producers, consumers, and general interest groups, 
that establishes the procedures by which 
accredited organizations create and maintain 
voluntary industry standards in the United States. 
ANSI. 

API (application program interface). A 

functional interface supplied by the operating 
system or by a separately orderable licensed 
program that allows an application program 
written in a high-level language to use specific 
data or functions of the operating system or the 
licensed program. IBM. 

application. (1) The use to which an 
information processing system is put; for 
example, a payroll application, an airline 
reservation application, a network application. 
IBM. (2) A collection of software components 
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used to perform specific types of user-oriented 
work on a computer. IBM. 

application program. A program written for or 
by a user that applies to the user's work, such as 
a program that does inventory control or payroll. 
IBM. 

argument. (1) A parameter passed between a 
calling program and a called program. IBM. 

(2) In a function call, an expression that 
represents a value that the calling function passes 
to the function specified in the call. Also called 
parameter. (3) In the shell, a parameter passed 
to a utility as the equivalent of a single string in 
the argv array created by one of the exec 
functions. An argument is one of the options, 
option-arguments, or operands following the 
command name. X/Open. 

array. In programming languages, an aggregate 
that consists of data objects, with identical 
attributes, each of which may be uniquely 
referenced by subscripting. IBM. 

array element. A data item in an array. IBM. 

ASCII (American National Standard Code for 
Information Interchange). The standard code, 
using a coded character set consisting of 7-bit 
coded characters (8 bits including parity check), 
that is used for information interchange among 
data processing systems, data communication 
systems, and associated equipment. The ASCII 
set consists of control characters and graphic 
characters. IBM. 

Note: IBM has defined an extension to ASCII 
code (characters 128-255). 

B 

backslash. The character \. This character is 
named <backslash> in the portable character set. 

binary stream. (1) An ordered sequence of 
untranslated characters. (2) A sequence of 
characters that corresponds on a one-to-one basis 
with the characters in the file. No character 
translation is performed on binary streams. IBM. 

blank character. (1) A graphic representation 
of the space character. ANSI. (2) A character 
that represents an empty position in a graphic 


character string. ISO Draft. (3) One of the 
characters that belong to the blank character class 
as defined via the LC_CTYPE category in the 
current locale. In the POSIX locale, a blank 
character is either a tab or a space character. 
X/Open. 

block. (1) In programming languages, a 
compound statement that coincides with the scope 
of at least one of the declarations contained 
within it. A block may also specify storage 
allocation or segment programs for other 
purposes. ISO-JTC1. (2) A string of data 
elements recorded or transmitted as a unit. The 
elements may be characters, words or physical 
records. ISO Draft. (3) The unit of data 
transmitted to and from a device. Each block 
contains one record, part of a record, or several 
records. 

boundary alignment. The position in main 
storage of a fixed-length field, such as a halfword 
or doubleword, on a byte-level boundary for that 
unit of information. IBM. 

brackets. The characters [ (left bracket) and ] 
(right bracket), also known as square brackets. 
When used in the phrase “enclosed in (square) 
brackets” the symbol [ immediately precedes the 
object to be enclosed, and ] immediately follows 
it. When describing these characters in the 
portable character set, the names <left-bracket> 
and <right-bracket> are used. X/Open. 

built-in. (1) A function that the compiler will 
automatically inline instead of making the 
function call, unless the programmer specifies not 
to inline. (2) In programming languages, 
pertaining to a language object that is declared by 
the definition of the programming language; for 
example the built-in function SIN in PL/I, the 
predefined data type INTEGER in FORTRAN. 
ISO-JTC1. Synonymous with predefined. IBM. 

C 

C++ class library. See class library. 

C++ library. A system library that contains 
common C++ language subroutines for file access, 
memory allocation, and other functions. 

call. To transfer control to a procedure, program, 
routine, or subroutine. IBM. 
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cast. In the C and C++ languages, an expression 
that converts the type of the operand to a 
specified data type (the operator). IBM. 

character. (1) A letter, digit, or other symbol 
that is used as part of the organization, control, or 
representation of data. A character is often in the 
form of a spatial arrangement of adjacent or 
connected strokes. ANSI. (2) A sequence of one 
or more bytes representing a single graphic 
symbol or control code. This term corresponds to 
the ISO C standard term multibyte character 
(multi-byte character), where a single-byte 
character is a special case of the multi-byte 
character. Unlike the usage in the ISO C 
standard, character here has no necessary 
relationship with storage space, and byte is used 
when storage space is discussed. X/Open. ISO.l. 

character array. An array of type char. X/Open. 

character class. A named set of characters 
sharing an attribute associated with the name of 
the class. The classes and the characters that they 
contain are dependent on the value of the 
LC_CTYPE category in the current locale. 
X/Open. 

character constant. (1) A constant with a 
character value. IBM. (2) A string of any of the 
characters that can be represented, usually 
enclosed in apostrophes. IBM. (3) In some 
languages, a character enclosed in apostrophes. 
IBM. 

character set. (1) A finite set of different 
characters that is complete for a given purpose; 
for example, the character set in ISO Standard 
646, 7-bit Coded Character Set for Information 
Processing Interchange. ISO Draft. (2) All the 
valid characters for a programming language or 
for a computer system. IBM. (3) A group of 
characters used for a specific reason; for example, 
the set of characters a printer can print. IBM. 

(4) See also portable character set. 

character string. A contiguous sequence of 
characters terminated by and including the first 
null byte. X/Open. 

child. A node that is subordinate to another 
node in a tree structure. Only the root node is 
not a child. 


class. (1) A C++ aggregate that may contain 
functions, types, and user-defined operators in 
addition to data. Classes may be defined 
hierarchically, allowing one class to be derived 
from another, and may restrict access to its 
members. (2) A user-defined data type. A class 
data type can contain both data representations 
(data members) and functions (member 
functions). 

class library. A collection of C++ classes. 

C library. A system library that contains 
common C language subroutines for file access, 
string operators, character operations, memory 
allocation, and other functions. IBM. 

code page. (1) An assignment of graphic 
characters and control function meanings to all 
code points; for example, assignment of 
characters and meanings to 256 code points for 
an 8-bit code, assignment of characters and 
meanings to 128 code points for a 7-bit code. 

(2) A particular assignment of hexadecimal 
identifiers to graphic characters. 

codeset. Synonym for code element set. IBM. 

collating element. The smallest entity used to 
determine the logical ordering of character or 
wide-character strings. A collating element 
consists of either a single character, or two or 
more characters collating as a single entity. The 
value of the LC_COLLATE category in the 
current locale determines the current set of 
collating elements. X/Open. 

collating sequence. (1) A specified arrangement 
used in sequencing. ISO-JTC1. ANSI. (2) An 
ordering assigned to a set of items, such that any 
two sets in that assigned order can be collated. 
ANSI. (3) The relative ordering of collating 
elements as determined by the setting of the 
LC_COLLATE category in the current locale. 

The character order, as defined for the 
LC_COLLATE category in the current locale, 
defines the relative order of all collating elements, 
such that each element occupies a unique position 
in the order. This is the order used in ranges of 
characters and collating elements in regular 
expressions and pattern matching. In addition, 
the definition of the collating weights of 
characters and collating elements uses collating 
elements to represent their respective positions 
within the collation sequence. 
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collection. (1) An abstract class without any 
ordering, element properties, or key properties. 

All abstract classes are derived from collection. 

(2) In a general sense, an implementation of an 
abstract data type for storing elements. 

Collection Class Library. A set of classes that 
provide basic functions for collections, and can be 
used as base classes. 

command. A request to perform an operation or 
run a program. When parameters, arguments, 
flags, or other operands are associated with a 
command, the resulting character string is a single 
command. 

condition. A relational expression that can be 
evaluated to a value of either true or false. IBM. 

const. (1) An attribute of a data object that 
declares the object cannot be changed. (2) A 
keyword that allows you to define a variable 
whose value does not change. 

constant. (1) In programming languages, a 
language object that takes only one specific value. 
ISO-JTC1. (2) A data item with a value that 
does not change. IBM. 

control character. (1) A character whose 
occurrence in a particular context specifies a 
control function. ISO Draft. (2) Synonymous 
with nonprinting character. IBM. (3) A 
character, other than a graphic character, that 
affects the recording, processing, transmission, or 
interpretation of text. X/Open. 

conversion. (1) In programming languages, the 
transformation between values that represent the 
same data item but belong to different data types. 
Information may be lost because of conversion 
since accuracy of data representation varies 
among different data types. ISO-JTC1. (2) The 
process of changing from one method of data 
processing to another or from one data processing 
system to another. IBM. (3) The process of 
changing from one form of representation to 
another; for example to change from decimal 
representation to binary representation. IBM. 

(4) A change in the type of a value. For 
example, when you add values having different 
data types, the compiler converts both values to a 
common form before adding the values. 


conversion descriptor. A per-process unique 
value used to identify an open codeset 
conversion. X/Open. 

coordinated universal time (UTC). Equivalent 
to Greenwich Mean Time (GMT) 

current working directory. (1) A directory, 
associated with a process, that is used in 
path-name resolution for path names that do not 
begin with a slash. X/Open. ISO.l. (2) The 
directory that is searched when a file name is 
entered with no indication of the directory that 
lists the file name. The operating system assumes 
that the current directory is the root directory 
unless a path to another directory is specified. 
IBM. (3) In the OS/2 operating system, the first 
directory in which the operating system looks for 
programs and files and stores temporary files and 
output. IBM. 

D 

data object. (1) A storage area used to hold a 
value. (2) Anything that exists in storage and on 
which operations can be performed, such as files, 
programs, classes, or arrays. (3) In a program, 
an element of data structure, such as a file, array, 
or operand, that is needed for the execution of a 
program and that is named or otherwise specified 
by the allowable character set of the language in 
which a program is coded. IBM. 

data stream. A continuous stream of data 
elements being transmitted, or intended for 
transmission, in character or binary-digit form, 
using a defined format. IBM. 

data type. The properties and internal 
representation that characterize data. 

DECS (double-byte character set). A set of 
characters in which each character is represented 
by 2 bytes. Languages such as Japanese, 

Chinese, and Korean, which contain more 
symbols than can be represented by 256 code 
points, require double-byte character sets. 

Because each character requires 2 bytes, the 
typing, display, and printing of DBCS characters 
requires hardware and programs that support 
DBCS. IBM. 
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declaration. (1) In the C and C++ languages, a 
description that makes an external object or 
function available to a function or a block 
statement. IBM. (2) Establishes the names and 
characteristics of data objects and functions used 
in a program. 

default locale. (1) The C locale, which is 
always used when no selection of locale is 
performed. (2) A system default locale, named 
by locale-related environmental variables. 

define directive. A preprocessor statement that 
directs the preprocessor to replace an identifier or 
macro invocation with special code. 

definition. (1) A data description that reserves 
storage and may provide an initial value. (2) A 
declaration that allocates storage, and may 
initialize a data object or specify the body of a 
function. 

delete. (1) A C++ keyword that identifies a free 
storage deallocation operator. (2) A C++ 
operator used to destroy objects created by new. 

device. A computer peripheral or an object that 
appears to the application as such. X/Open. 

ISO.l. 

directory. A type of file containing the names 
and controlling information for other files or 
other directories. IBM. 

display. To direct the output to the user's 
terminal. If the output is not directed to the 
terminal, the results are undefined. X/Open. 

dot. The file name consisting of a single dot 
character (.). X/Open. ISO.l. 

double-byte character set. See DBCS. 

double-precision. Pertaining to the use of two 
computer words to represent a number in 
accordance with the required precision. 

ISO-JTC1. ANSI. 

dump. To copy data in a readable format from 
main or auxiliary storage onto an external 
medium such as tape, diskette, or printer. IBM. 

dynamic. Pertaining to an operation that occurs 
at the time it is needed rather than at a 
predetermined or fixed time. IBM. 


E 

EBCDIC (extended binary-coded decimal 
interchange code). A coded character set of 256 
8-bit characters. IBM. 

E-format. Floating-point format, consisting of a 
number in scientific notation. IBM. 

element. The component of an array, subrange, 
enumeration, or set. 

empty string. (1) A string whose first byte is a 
null byte. Synonymous with null string. X/Open. 
(2) A character array whose first element is a 
null character. ISO.l. 

epoch. The time zero hours, zero minutes, zero 
seconds, on January 1, 1970 Coordinated 
Universal Time. X/Open. ISO.l. 

exception. (1) Any user, logic, or system error 
detected by a function that does not itself deal 
with the error but passes the error on to a 
handling routine (also called throwing the 
exception). (2) In programming languages, an 
abnormal situation that may arise during 
execution, that may cause a deviation from the 
normal execution sequence, and for which 
facilities exist in a programming language to 
define, raise, recognize, ignore, and handle it; for 
example, (ON-) condition in PL/I, exception in 
ADA. ISO-JTC1. 

exception handler. (1) Exception handlers are 
catch blocks in C++ applications. Catch blocks 
catch exceptions when they are thrown from a 
function enclosed in a try block. Try blocks, 
catch blocks, and throw expressions are the 
constructs used to implement formal exception 
handling in C++ applications. (2) A set of 
routines used to detect deadlock conditions or to 
process abnormal condition processing. An 
exception handler allows the normal running of 
processes to be interrupted and resumed. IBM. 

executable file. A regular file acceptable as a 
new process image file by the equivalent of the 
exec family of functions, and thus usable as one 
form of a utility. The standard utilities described 
as compilers can produce executable files, but 
other unspecified methods of producing 
executable files may also be provided. The 
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internal format of an executable file is 
unspecified, but a conforming application cannot 
assume an executable file is a text file. X/Open. 

extension. (1) An element or function not 
included in the standard language. (2) File name 
extension. 

F 

file mode. An object containing the file mode 
bits and file type of a file, as described in 
<sys/stat.h>. X/Open. 

file mode bits. A file's file permission bits, 
set-user-ID-on-execution bit (S_ISUID) and 
set-group-ID-on-execution bit (S_ISGID). 

X/Open. 

file scope. A name declared outside all blocks 
and classes has file scope and can be used after 
the point of declaration in a source file. 

for statement. A looping statement that contains 
the word for followed by a list of expressions 
enclosed in parentheses (the condition) and a 
statement (the action). Each expression in the 
parenthesized list is separated by a semicolon. 

You can omit any of the expressions, but you 
cannot omit the semicolons. 

function. A named group of statements that can 
be called and evaluated and can return a value to 
the calling statement. IBM. 

function call. An expression that moves the path 
of execution from the current function to a 
specified function and evaluates to the return 
value provided by the called function. A function 
call contains the name of the function to which 
control moves and a parenthesized list of values. 
IBM. 

G 

global. Pertaining to information available to 
more than one program or subroutine. IBM. 

global variable. A symbol defined in one 
program module that is used in other 
independently compiled program modules. 


GMT (Greenwich Mean Time). The solar time 
at the meridian of Greenwich, formerly used as 
the prime basis of standard time throughout the 
world. GMT has been superseded by coordinate 
universal time (UTC). 

Greenwich Mean Time. See GMT. 

H 

header file. A text file that contains declarations 
used by a group of functions, programs, or users. 

heap. An unordered flat collection that allows 
duplicate elements. 

I 

I18N. Abbreviation for internationalization. 

identifier. (1) One or more characters used to 
identify or name a data element and possibly to 
indicate certain properties of that data element. 
ANSI. (2) In programming languages, a token 
that names a data object such as a variable, an 
array, a record, a subprogram, or a function. 

ANSI. (3) A sequence of letters, digits, and 
underscores used to identify a data object or 
function. IBM. 

if statement. A conditional statement that 
contains the keyword if, followed by an 
expression in parentheses (the condition), a 
statement (the action), and an optional else clause 
(the alternative action). IBM. 

include directive. A preprocessor directive that 
causes the preprocessor to replace the statement 
with the contents of a specified file. 

include file. See header file. 

input stream. A sequence of control statements 
and data submitted to a system from an input 
unit. Synonymous with input job stream, job 
input stream. IBM. 

instance. An object-oriented programming term 
synonymous with object. An instance is a 
particular instantiation of a data type. It is simply 
a region of storage that contains a value or group 
of values. For example, if a class box is 
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previously defined, two instances of a class box 
could be instantiated with the declaration: 
box boxl, box2; 

instruction. A program statement that specifies 
an operation to be performed by the computer, 
along with the values or locations of operands. 
This statement represents the programmer's 
request to the processor to perform a specific 
operation. 

internationalization. The capability of a 
computer program to adapt to the requirements of 
different native languages, local customs, and 
coded character sets. X/Open. 

Synonymous with II8N. 

iteration. The process of repeatedly applying a 
function to a series of elements in a collection 
until some condition is satisfied. 

K 

key access. A property that allows elements to 
be accessed by matching keys. 

keyword. (1) A predefined word reserved for 
the C and C++ languages, that may not be used as 
an identifier. (2) A symbol that identifies a 
parameter in JCL. 

L 

label. An identifier within or attached to a set of 
data elements. ISO Draft. 

library. (1) A collection of functions, calls, 
subroutines, or other data. IBM. (2) A set of 
object modules that can be specified in a link 
command. 

link. To interconnect items of data or portions 
of one or more computer programs; for example, 
linking of object programs by a linkage editor to 
produce an executable file. 

linker. A computer program for creating load 
modules from one or more object modules by 
resolving cross references among the modules 
and, if necessary, adjusting addresses. IBM. 


literal. (1) In programming languages, a lexical 
unit that directly represents a value; for example, 
14 represents the integer fourteen, “APRIL” 
represents the string of characters APRIL, 
3.0005E2 represents the number 300.05. 
ISO-JTC1. (2) A symbol or a quantity in a 
source program that is itself data, rather than a 
reference to data. IBM. (3) A character string 
whose value is given by the characters 
themselves; for example, the numeric literal 7 has 
the value 7, and the character literal 
CHARACTERS has the value CHARACTERS. 
IBM. 

local. (1) In programming languages, pertaining 
to the relationship between a language object and 
a block such that the language object has a scope 
contained in that block. ISO-JTC1. 

(2) Pertaining to that which is defined and used 
only in one subdivision of a computer program. 
ANSI. 

locale. The definition of the subset of a user's 
environment that depends on language and 
cultural conventions. X/Open. 

lvalue. An expression that represents a data 
object that can be both examined and altered. 

M 

macro. An identifier followed by arguments 
(may be a parenthesized list of arguments) that 
the preprocessor replaces with the replacement 
code located in a preprocessor #define directive. 

mask. A pattern of characters that controls the 
keeping, deleting, or testing of portions of another 
pattern of characters. ISO-JTC1. ANSI. 

member. A data object or function in a 
structure, union, or class. Members can also be 
classes, enumerations, bit fields, and type names. 

method. In the C++ language, a synonym for 
member function. 

migrate. To move to a changed operating 
environment, usually to a new release or version 
of a system. IBM. 

mode. A collection of attributes that specifies a 
file's type and its access permissions. X/Open. 
750.7. 
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module. A program unit that usually performs a 
particular function or related functions, and that is 
distinct and identifiable with respect to compiling, 
combining with other units, and loading. 

multibyte character. A mixture of single-byte 
characters from a single-byte character set and 
double-byte characters from a double-byte 
character set. 

multitasking. A mode of operation that allows 
concurrent performance, or interleaved execution 
of two or more tasks. ISO-JTC1. ANSI. 

N 

name. In the C++ language, a name is 
commonly referred to as an identifier. However, 
syntactically, a name can be an identifier, 
operator function name, conversion function 
name, destructor name or qualified name. 

NULL. In the C and C++ languages, a pointer 
that does not point to a data object. IBM. 

null character (NUL). The ASCII or EBCDIC 
character '\0' with the hex value 00, all bits turned 
off. It is used to represent the absence of a 
printed or displayed character. This character is 
named <NUL> in the portable character set. 

null pointer. The value that is obtained by 
converting the number 0 into a pointer; for 
example, (void *) 0. The C and C++ languages 
guarantee that this value will not match that of 
any legitimate pointer, so it is used by many 
functions that return pointers to indicate an error. 
X/Open. 

null string. (1) A string whose first byte is a 
null byte. Synonymous with empty string. 
X/Open. (2) A character array whose first 
element is a null character. ISO.l. 

null value. A parameter position for which no 
value is specified. IBM. 


O 

object. (1) A region of storage. An object is 
created when a variable is defined or new is 
invoked. An object is destroyed when it goes out 
of scope. (See also instance.) (2) In 
object-oriented design or programming, an 
abstraction consisting of data and the operations 
associated with that data. See also class. IBM. 

(3) An instance of a class. 

open file. A file that is currently associated with 
a file descriptor. X/Open. ISO.l. 

operating system (OS). Software that controls 
functions such as resource allocation, scheduling, 
input/output control, and data management. 

operator precedence. In programming 
languages, an order relation defining the sequence 
of the application of operators within an 
expression. ISO-JTC1. 

overflow. (1) A condition that occurs when a 
portion of the result of an operation exceeds the 
capacity of the intended unit of storage. (2) That 
portion of an operation that exceeds the capacity 
of the intended unit of storage. IBM. 

P 

parameter. (1) In the C and C++ languages, an 
object declared as part of a function declaration 
or definition that acquires a value on entry to the 
function, or an identifier following the macro 
name in a function-like macro definition. X/Open. 
(2) Data passed between programs or procedures. 
IBM. 

parent process. (1) The program that originates 
the creation of other processes by means of spawn 
or exec function calls. See also child process. 

(2) A process that creates other processes. 

path name. (1) A string that is used to identify 
a file. A path name consists of, at most, 
{PATH_MAX} bytes, including the terminating 
null character. It has an optional beginning slash, 
followed by zero or more file names separated by 
slashes. If the path name refers to a directory, it 
may also have one or more trailing slashes. 
Multiple successive slashes are considered to be 
the same as one slash. A path name that begins 
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with two successive slashes may be interpreted in 
an implementation-dependent manner, although 
more than two leading slashes will be treated as a 
single slash. The interpretation of the path name 
is described in pathname resolution. ISO.l. 

(2) A file name specifying all directories leading 
to the file. 

period. The character (.). The term period is 
contrasted against dot , which is used to describe a 
specific directory entry. This character is named 
<period> in the portable character set. 

pointer. In the C and C++ languages, a variable 
that holds the address of a data object or a 
function. IBM. 

portable character set. The set of characters 
specified in POSIX 1003.2, section 2.4. 

portability. The ability of a programming 
language to compile successfully on different 
operating systems without requiring changes to 
the source code. 

positional parameter. A parameter that must 
appear in a specified location relative to other 
positional parameters. IBM. 

precedence. The priority system for grouping 
different types of operators with their operands. 

predefined macros. Frequently used routines 
provided by an application or language for the 
programmer. 

preprocessor. A phase of the compiler that 
examines the source program for preprocessor 
statements that are then executed, resulting in the 
alteration of the source program. 

printable character. One of the characters 
included in the print character classification of the 
LC_CTYPE category in the current locale. 
X/Open. 

process. (1) An instance of an executing 
application and the resources it uses. (2) An 
address space and single thread of control that 
executes within that address space, and its 
required system resources. X/Open. ISO.l. 

process ID. The unique identifier representing a 
process. A process ID is a positive integer. 
(Under ISO only, it is a positive integer that can 


be contained in a pid_t.) A process ID will not 
be reused by the system until the process lifetime 
ends. In addition, if there exists a process group 
whose process group ID is equal to that process 
ID, the process ID will not be reused by the 
system until the process group lifetime ends. A 
process that is not a system process will not have 
a process ID of 1. X/Open. ISO.l. 

public. Pertaining to a class member that is 
accessible to all functions. 

R 

redirection. In the shell, a method of 
associating files with the input or output of 
commands. X/Open. 

reentrant. The attribute of a program or routine 
that allows the same copy of a program or routine 
to be used concurrently by two or more tasks. 

regular expression. (1) A mechanism to select 
specific strings from a set of character strings. 

(2) A set of characters, meta-characters, and 
operators that define a string or group of strings 
in a search pattern. (3) A string containing 
wildcard characters and operations that define a 
set of one or more possible strings. 

root. In the OS/2 operating system, the base 
directory. 

runtime library. A compiled collection of 
functions whose members can be referred to by 
an application program during runtime execution. 
Typically used to refer to a dynamic library that 
is provided in object code, such that references to 
the library are resolved during the linking step. 
The runtime library itself is not statically bound 
into the application modules. 

S 

scope. (1) That part of a source program in 
which a variable is visible. (2) That part of a 
source program in which an object is defined and 
recognized. 

semaphore. An object used by multithread 
applications for signalling purposes and for 
controlling access to serially reusable resources. 
Processes can be locked to a resource with 
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semaphores if the processes follow certain 
programming conventions. 

sequence. A sequentially ordered flat collection. 

signal. (1) A condition that may or may not be 
reported during program execution. For example, 
SIGFPE is the signal used to represent erroneous 
arithmetic operations such as a division by zero. 
(2) A mechanism by which a process may be 
notified of, or affected by, an event occurring in 
the system. Examples of such events include 
hardware exceptions and specific actions by 
processes. The term signal is also used to refer 
to the event itself. X/Open. ISO.l. 

signal handler. A function to be called when 
the signal is reported. 

space character. The character defined in the 
portable character set as <space>. The space 
character is a member of the space character class 
of the current locale, but represents the single 
character, and not all of the possible members of 
the class. X/Open. 

specifiers. Used in declarations to indicate 
storage class, fundamental data type and other 
properties of the object or function being 
declared. 

standard error (stderr). An output stream 
usually intended to be used for diagnostic 
messages. X/Open. 

standard input (stdin). (1) An input stream 
usually intended to be used for primary data 
input. X/Open. (2) The primary source of data 
entered into a command. Standard input comes 
from the keyboard unless redirection or piping is 
used, in which case standard input can be from a 
file or the output from another command. IBM. 

standard output (stdout). (1) An output stream 
usually intended to be used for primary data 
output. X/Open. (2) In the AIX operating 
system, the primary destination of data coming 
from a command. Standard output goes to the 
display unless redirection or piping is used, in 
which case standard output can go to a file or to 
another command. IBM. 

statement. An instruction that ends with the 
character ; (semicolon) or several instructions that 
are surrounded by the characters { and }. 


static. A keyword used for defining the scope 
and linkage of variables and functions. For 
internal variables, the variable has block scope 
and retains its value between function calls. For 
external values, the variable has file scope and 
retains its value within the source file. For class 
variables, the variable is shared by all objects of 
the class and retains its value within the entire 
program. 

stream. (1) A continuous stream of data 
elements being transmitted, or intended for 
transmission, in character or binary-digit form, 
using a defined format. (2) A file access object 
that allows access to an ordered sequence of 
characters, as described by the ISO C standard. 
Such objects can be created by the f do pen or 
fopen functions, and are associated with a file 
descriptor. A stream provides the additional 
services of user-selectable buffering and 
formatted input and output. X/Open. 

stream buffer. A stream buffer is a buffer 
between the ultimate consumer, ultimate 
producer, and the I/O Stream Library functions 
that format data. It is implemented in the I/O 
Stream Library by the streambuf class and the 
classes derived from streambuf. 

string. A contiguous sequence of bytes 
terminated by and including the first null byte. 
X/Open. 

string constant. Zero or more characters 
enclosed in double quotation marks. 

struct. An aggregate of elements, having 
arbitrary types. 

structure. A construct (a class data type) that 
contains an ordered group of data objects. Unlike 
an array, the data objects within a structure can 
have varied data types. A structure can be used 
in all places a class is used. The initial projection 
is public. 

subsystem. A secondary or subordinate system, 
usually capable of operating independently of or 
asynchronously with, a controlling system. ISO 
Draft. 

support. In system development, to provide the 
necessary resources for the correct operation of a 
functional unit. IBM. 
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T 

text file. A file that contains characters 
organized into one or more lines. The lines must 
not contain NUL characters and none can exceed 
{LINE_MAX}—which is defined in 
limits.h—bytes in length, including the new-line 
character. The term text file does not prevent the 
inclusion of control or other non-printable 
characters (other than NUL). X/Open. 

this. A C++ keyword that identifies a special 
type of pointer in a member function, that 
references the class object with which the 
member function was invoked. 

thread. The smallest unit of operation to be 
performed within a process. IBM. 

tilde. The character ~. This character is named 
<tilde> in the portable character set. 

token. The smallest independent unit of meaning 
of a program as defined either by a parser or a 
lexical analyzer. A token can contain data, a 
language keyword, an identifier, or other parts of 
language syntax. IBM. 

trap. An unprogrammed conditional jump to a 
specified address that is automatically activated 
by hardware. A recording is made of the location 
from which the jump occurred. ISO-JTC1. 

type. The description of the data and the 
operations that can be performed on or by the 
data. See also data type. 

type conversion. Synonym for boundary 
alignment. 

type definition. A definition of a name for a 
data type. IBM. 

type specifier. Used to indicate the data type of 
an object or function being declared. 

U 

underflow. (1) A condition that occurs when 
the result of an operation is less than the smallest 
possible nonzero number. (2) Synonym for 
arithmetic underflow, monadic operation. IBM. 

union. (1) In the C or C++ language, a variable 


that can hold any one of several data types, but 
only one data type at a time. IBM. (2) For bags, 
there is an additional rule for duplicates: If bag P 
contains an element m times and bag Q contains 
the same element n times, then the union of P 
and Q contains that element m+n times. 

V 

variable. In programming languages, a language 
object that may take different values, one at a 
time. The values of a variable are usually 
restricted to a certain data type. ISO-JTC1. 

W 

while statement. A looping statement that 
contains the keyword while followed by an 
expression in parentheses (the condition) and a 
statement (the action). IBM. 

white space. (1) Space characters, tab 
characters, form-feed characters, and new-line 
characters. (2) A sequence of one or more 
characters that belong to the space character class 
as defined via the LC_CTYPE category in the 
current locale. In the POSIX locale, white space 
consists of one or more blank characters (space 
and tab characters), new-line characters, 
carriage-return characters, form-feed characters, 
and vertical-tab characters. X/Open. 

wide character. A character whose range of 
values can represent distinct codes for all 
members of the largest extended character set 
specified among the supporting locales. 

wide-character string. A contiguous sequence 
of wide-character codes terminated by and 
including the first null wide-character code. 
X/Open. 

working directory. Synonym for current 
working directory. 
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end of file, determining 197 
end-of-file indicator 94, 222 
end-of-stream 
I/O 222 
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ending a program 47 
ending threads 195 
_endthread function 195 
Enhanced editor (EPM) 
environment table 305 
environment variables 305 

modifying from within program 471 
environment-affecting functions 23 
EOF 

clearing 497 
macro 815 

resetting error indicator 94 

__eof function 197 

EPM 

See Enhanced editor (EPM) 

ERANGE 803 
erf function 199 
erfc function 199 
errno 803 
errno variable 459 
errno.h include file 803 
error handling functions 9 
error indicator 223 
clearing 497 
error messages 459 
pointing to 580 
printing 580 
exception masking 109 
_exception_dl Unit function 

refid termin.DLL environment 122 
_exec functions 
_execlpe 200 
_execvpe 200 
execl 200 
execle 200 
execlp 200 
execv 200 
execve 200 
execvp 200 
_exit function 204, 205 
EXIT_FAILURE 204, 817 
EXIT_SUCCESS 204, 817 
exiting 

a process 205 
a program 204 
exp function 206 
extensions to standards 
library functions 
_access 49 
_alloca 53 
_atold 69 


extensions to standards (continued) 
library functions (continued) 
_beginthread 71 
_cabs 78 
_cgets 85 
_chdir 87 
_chdrive 89 
_chmod 90 
_chsize 92 
_clear87 95 
_close 99 
_control87 109 
_cprintf function 113 
_cputs 114 
_creat 115 
_cscanf function 127 
_cwait 131 
_debug_calloc 139 
_debug_free 141 
_debug_heapmin 143 
_debug_malloc 145 
_debug_realloc 147 
_debug_tfree 151 
_debug_trealloc 157 
_disable 168 
_dump_allocated 180 
_dup 186 
_dup2 189 
_ecvt 192 
_enable 194 
_endthread 195 
_eof 197 
_execl 200 
_execle 200 
_execlp 200 
_execlpe 200 
_execv 200 
_execve 200 
_execvp 200 
_execvpe 200 
_exit 205 
_f2xml 292 
_facos 208, 214 
_fasin 210 
_fcloseall 213 
_fcos 

_fcossin 215 
_fcvt 217 
_fdopen 219 
_fgetchar 227 
_filelength 236 
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extensions to standards (continued) 
library functions (continued) 
_fileno 238 
_flushall 240 
_fpatan 246 
_fpreset 247 
_fptan 251 
_fputchar 254 
_freemod 265 
_fsin 277 
_fsincos 278 
_fsqrt 280 
_fstat 281 
_ftime 285 
_fullpath 287 
_fyl2x 290 
_fyl2xpl 291 
_gcvt 294 
_getch 298 
_getche 298 
_getcwd 300 
_getdcwd 302 
_getdrive 304 
_getpid 308 
_getTIB value 313 
_heap_check 323 
_heapmin 327 
_inp 340 
_inpd 342 
_inpw 344 
_interrupt 346 
_isascii 350 
_iscsym 356 
_iscsymf 356 
_itoa 368 
_kbhit 369 
Jfind 374 
_loadmod 376 
_lrotl 392 
_lrotr 392 
_lsearch 374 
_lseek 393 
_ltoa 395 
_makepath 401 
_matherr 
max macro 408 
memccpy 424 
memicmp 429 
min 435 
_mkdir 436 
_msize 441 


extensions to standards (continued) 
library functions (continued) 
_onexit 445 
_open 447 
_outp 450 
_outpd 452 
_outpw 454 

_parmdwords 456 

_putch 470 

_putenv 471 

_read 482 

_rmdir 499 

_rmtmp 513 

_rotl 514 

_rotr 514 

_searchenv 523 

_set_crt_msg_handle 526 

_setmode 535 

signal 540 

_sopen 545 

_spawnl 548 

_spawnle 548 

_spawnlp 548 

_spawnlpe 548 

_spawnv 548 

_spawnve 548 

_spawnvp 548 

_spawnvpe 548 

_splitpath 552 

_stat 561 

_status87 563 

_strdate 577 

strdup 578 

_strerror 580 

stricmp 591 

strlwr 594 

strnicmp 601 

_strtime 617 

strtold 627 

strupr 631 

_swab 634 

system 639 

_tcalloc 647 

_tell 655 

_tempnam 657 

_tfree 659 

_threadstore 665 

_tmalloc 667 

_toascii 673 

_tolower 673 

_toupper 673 
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extensions to standards (continued) 
library functions (continued) 
_trealloc 679 
_tzset 681 
_ultoa 716 
_umask 719 
_ungetch 723 
unlink 729 
_utime 734 
_wait 

_write 799 
predefined macros 849 

F 

_f2xml function 292 
fabs function 207 
_facos function 208, 214 
_fasin function 210 
_fclose function 212 
_fcloseall function 213 
fcntl.h 803 
_fcos function 
_fcossin function 215 
_fcvt function 217 
_fdopen function 219 
feof function 222 
ferror function 223 
_fflush function 224 
fgetc function 225 
_fgetchar function 227 
fgetpos function 228 
_fgets function 230 
fgetwc 232 
fgetws function 234 
file errors 94 
file handles 186, 189 
changing 526 

file management functions 10 

file modification time, setting 734 

file name length 815 

file names, temporary 815 

file pointer, move 393 

file positioning 228, 273, 275, 283 

file status information 561 

FILE type 816 

_filelength function 236 

_fileno function 238 

files 

appending to 220 


files (continued) 

changing permission mode 90 

create and open 115 

creating temporary 657 

deleting 729 

handle 238 

include 801 

maximum opened 815 

name length 815 

positioning 497 

renaming 496 

searching for 523 

setting modification time 734 

sharing 545 

status information 561 

temporary 

See temporary files 
unlinking 729 
updating 219 
float.h include file 803 
floating point 
control word 
setting 109 
converting 

to string 192, 217, 294 
exception masking 109 
fast execution 
status word 
clearing 95 
getting 563 
unit, resetting 247 
floor function 239 
_flushall function 240 
flushing buffers 224, 240 
fmod function 242 
fopen function 243 

fopen, maximum simultaneous files 815 

formatted I/O 249 

_fpatan function 246 

fpos_t 816 

_fpreset function 247 

fprintf function 249 

_fptan function 251 

fputc function 252 

character to stdout 254 
_fputchar function 254 
fputs function 255 
fputwc function 257 
fputws function 259 
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fread function 261 
free function 263 
freeing 

memory 151 
storage 141, 151, 263 
tiled storage 659 
user DLLs 265 
_freemod function 265 
freopen function 268 
frexp function 270 
fscanf function 271 
fseek function 273 
fsetpos function 275 
_fsin function function 277 
_fsincos function 278 
_fsqrt function 280 
_fstat function 281 
ftell function 283 
_ftime function 285 
_fullpath. function 287 
function declarations 801 
functions 

See also extensions to standards 
built-in 53, 456 
classification of 825 
debug memory management 
inlined 27 
table of 826—848 
fwrite function 289 
_fyl2x function 290 
_fyl2xpl function 291 

G 

gamma function 293 
_gcvt function 294 
getc function 296 
_getch function 298 
getchar function 296 
_getche function 298 
_getcwd function 300 
_getdcwd function 302 
_getdrive function 304 
getenv function 305 
getmccol 1 function 306 
_getpid function 308 
gets function 309 
getsyntx function 311 
_getTIB value function 313 


getting 

character property handle 795 
collating elements 306, 319 
current drive 304 
current file position 283 
current working directory 300, 302 
directory status information 561 
file length 236 
file position 228 
file status information 561 
floating-point status word 563 
full path name 287 
information about heap 732 
information about memory 180, 183, 652, 
699, 702 

pointer position 655 
process identifier 308 
size of parameter list 456 
thread information block value 313 
wide character from stdin 317 
getwc function 315 
getwchar function 317 
getwmccoll function 319 
global variables 
errno 459 
P_tmpdir 657 
gmtime function 321 


H 

handling interrupt signals 540 
heap 

checking storage in 323 
getting information about 699, 702, 732 
returning memory from 143, 327, 663 
heap checking functions 21 
heap creation functions 22 
_heap_check function 323 
_heapmin function 327 
HUGE 78,811 
HUGEJVAL 78,811 
hyperbolic 
cosine 112 
sine 544 
tangent 646 
hypot function 333 
hypotenuse 333 
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I 

I/O errors 94 
I/O functions 
low-level 17 
stream 15 
iconv function 334 
i conv_cl ose function 337 
iconv_open function 338 
iconv.h include file 804 
include files 
assert.h 801 
builtin.h 801 
collate.h 802 
conio.h 802 
ctype.h 802 
direct.h 803 
errno.h 803 
fcntl.h 803 
float.h 803 
iconv.h 804 
io.h 804 
limits.h 806 
locale.h 806 
malloc .h 810 
math.h 811 
memory, h 811 
monetary .h 812 
nl_types.h 812 
process.h 812 
regex.h 813 
search.h 813 
setjmp.h 813 
share.h 814 
signal.h 814 
stdarg.h 814 
stddef.h 814 
stdio.h 815 
stdlib.h 816 
string.h 818 
sys\stat.h 819 
sys\timeb.h 819 
sys\types.h 819 
sys\utime.h 819 
time.h 819 
umalloc.h 820 
wcstr.h 823 
wctype.h 823 
whcar.h 821 


indicators, error 94 
infinity values 
description 33 
in library functions 

math functions 38, 41 
printf family 36 
scant family 35 
string conversion functions 37 
macro constants for 34 
initializing 

constructors and destructors 118 
DLL environment 118 
storage 

strings 599, 603 
_inp function 340 
_inpd function 342 
input/output (I/O) stream 
access mode 268 
appending 243, 268 
binary mode 268 
buffering 524 

changing current file position 273, 283 
changing file position 497 
closing 212 

formatted I/O 271, 461, 517, 554, 559 
opening 243 

reading characters 225, 296 
reading data items 261, 340, 342, 344 
reading lines 230, 309 
reopening 268 
rewinding 497 
text mode 268 
translation mode 268 
ungetting characters 721 
updating 243, 268 
writing characters 252, 468 
writing data items 289, 450, 452, 454 
writing lines 473 
writing strings 255 
_inpw function 344 
integers 

converting to strings 368, 395, 716 
pseudo-random 481 
_interrupt function 346 
interrupts 

calling 346 
disabling 168 
enabling 194 
io. h include file 804 
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i s a 1 n um function 347 
i s a 1 p h a function 347 
_isascii function 350 
_isatty function 352 
i sbl ank function 354 
iscntrl function 347 
_iscsym function 356 
_iscsymf function 356 
i s d i g i t function 347 
i sgraph function 347 
i si ower function 347 
ismccollel function 358 
isprint function 347 
i spunct function 347 
i sspace function 347 
i supper function 347 
i swal num function 360 
i swbl ank function 363 
iswcntrl function 360 
i swctype function 365 
i swdigi t function 360 
i swgraph function 360 
i swl ower function 360 
i swprint function 360 
i swpunct function 360 
i swspace function 360 
i swupper function 360 
iswxdi git function 360 
i sxdigi t function 347 
_itoa function 368 

J 

_j0,_jl,_jn (bessel functions) 74 

K 

_kbhit function 369 

keyboard, writing characters to 723 

keystrokes, checking for 369 

L 

labs function 371 
ldexp function 372 
ldiv function 373 
length function 593 
length in bytes, file 236 
_lfind function 374 


_LHUGE 811 
_LHUGE_VAL 811 
library functions 

See also functions, extensions to SAA 
classification of 825 
infinity and NaN values in 35 
intrinsic 27 
table of 826—848 
library introduction 9 
limits.h include file 806 
lines 

reading 230 
writing 473 
loading DLLs 376 
_loadmod function 376 
local time 

copying into buffer 617 
difference from Universal Time 285 
file modification 734 
obtaining 285 
local time corrections 385 
1 ocal dtconv function 379 
locale functions 23 
locale.h include file 806 
localeconv function 381 
localtime function 385 
locating storage 263 
log function 387 
log 10 function 388 
logic errors 59 
logical record length 244 
longjmp function 389 
loss of significance errors 405 
lrecl 244 
_lrotl function 392 
_lrotr function 392 
_lsearch function 374 
_lseek function 393 
_ltoa function 395 
_lxchg function 397 

M 

macros 

_DEBUG_ALLOC_ 

for NaN and infinity values 34 
max 408 
min 435 
predefined 849 
_TILED_ 
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_makepath function 401 

malloc function 403 

malloc.h include file 810 

masking floating-point exceptions 109 

math functions 

infinity and NaN values in 38, 41 
math.h include file 811 
mathematical functions 11 
_matherr function 405 
max function 408 
maxcol1 function 408 
maximum 

file name 815 
opened files 815 
temporary file name 815 
MB_CUR_MAX 817 
mblen function 411 
mb rl en function 413 
mbrtowc function 415 
mbsinit function 417 
mbsrtowcs function 418 
mbstowes function 420 
mbtowe function 422 
memccpy function 424 
memchr function 425 
mememp function 426 
memepy function 428 
memiemp function 429 
memmove function 431 
memory 

See also storage 
checking blocks of 323 
returning from heap 327, 663 
memory allocation functions 20 
memory attribute 
freeing 141, 151 

getting information about 180, 183, 649, 
652, 699, 702 
returning from heap 143 
memory management functions 20 
memory object functions 23 
memory.h include file 811 
memset function 432 
min macro 435 
miscellaneous functions 
misfunc.miscellaneous functions 
_mkdir function 436 
mktime function 438 
modf function 440 


modification time, file 734 
modifying environment variables 471 
monetary functions 13 
monetary.h include file 812 
_msize function 441 
multibyte conversions 

from wide character 747, 793 
from wide-character string 774, 784 
multithread programs 
&I2 @ MULTITH. 

ending threads 195 
creating threads 71 

N 

NaN (not-a-number) values 
description 33 
in library functions 

math functions 38, 41 
printf family 36 
scant family 35 
string conversion functions 37 
macro constants for 34 
NDEBUG 59, 801 
nl_langinfo function 443 
at end of program 445 
nl_types.h include file 812 
nonlocal goto 389, 528 
NULL pointer 814, 816, 817 

O 

offsetof macro 814 


_onexit function 

445 

open flag 447 


_open function 

447 

OS/2 


publications 

865 

_outp function 

450 

_outpd function 

452 

_outpw function 

454 

overflow error 

405 


P 

P_tmpdir 815 
P_tmpdir variable 657 
parent process 
delaying 131 
end of 200 
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parent process (continued) 
overlaying of 202 
passing envrionment to child 549 
suspension of 548 
waiting for exit of child 205 

_parmdwords function 456 

passing 

arguments 131 

commands within a program 639 
environment setting 201 
from child process 131 
to child process 
arguments 201 
environment settings 549 
values to child thread 71 
path names 

creating 401 
decomposing 552 
getting 287 

permission mask file 719 
permission settings 


changing 90 

determining 

49 

file 115 


perror function 

459 

pointer position 

655 

pointers 


portability 


publications 

865 


standards to follow 1 
pow function 460 
predefined macros 849 
printf function 461 
printf functions 

infinity and NaN values in 36 
printing 

characters to screen 113 
data items from stream 289 
process control functions 9 
process.h include file 812 
processes 
child 

See child processes 
identifier 308 
spawning 548 
pseudo-random integers 481 
pseudorandom number functions 20 
ptrdiff_t 814 
pushing characters 721 


putc function 468 
_putch function 470, 482 
putchar function 468 
_putenv function 471 
puts function 473 
putwc function 474 
putwchar function 476 

Q 

qsort function 478 
quick sort 478 

R 

raise function 480 
rand function 481 
RAND_MAX 817 
random access 273, 283 
random number generator 481, 557 
read operations 225 

character from stdin 225 
read operations from keyboard 298 
read to buffer, file 482 
realloc function 484 
reallocation 484 
recfm 244 
record format 244 
redirection 268 
regcomp function 487 
regerror function 489 
regex.h include file 813 
r eg exec function 491 
regfree function 494 
regular expression functions 11 
regular expressions 
compiling 487 
remove function 495 
removing 

temporary files 513 
rename function 496 
renaming 
files 496 

reopening streams 268 
reserving 
storage 

_debug_calloc 139 
_tcalloc 647 
calloc 80 
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resetting floating-point unit 247 
reversing strings 612 
rewind function 497 
rewinding 

a stream 497 
_rmdir function 499 
_rmtmp function 513 
rotating bits 392 
characters 117 
unsigned integer value 514 
unsigned short values 558 
_rotl function 514 
_rotr function 514 
rpmatch function 516 

S 

SAA functions 
absolute value 
abs 48 
fabs 207 
labs 371 

character classification and conversion 
tolower 676 
toupper 676 
data conversion 
atof 63 
atoi 65 
atol 67 

differential equations 
bessel 74 
exponential 
exp 206 
frexp 270 
ldexp 372 
log 387 
log10 388 
pow 460 
file handling 
remove 495 
rename 496 
tmpnam 672 
locale 

localeconv 381 
logarithmic 
log 387 
log10 388 
math 

acos 51 
asin 57 
atan 61 


SAA functions (continued) 
math (continued) 
atan2 61 
bessel 74 
ceil 84 
cos 111 
cosh 112 
div 169 
erf 199 
erfc 199 
exp 206 
fabs 207 
floor 239 
fmod 242 
frexp 270 
gamma 293 
hypot 333 
ldexp 372 
ldiv 373 
log 387 
log10 388 
modf 440 
sin 543 
sinh 544 
sqrt 556 
tan 645 
tanh 646 
memory allocation 
calloc 80 
free 263 
malloc 403 
realloc 484 
memory operations 
memchr 425 
memcmp 426 
memcpy 428 
memmove 431 
memset 432 
miscellaneous 
assert 59 
getenv 305 
longjmp 389 
perror 459 
rand 481 
setjmp 528 
srand 557 
multibyte 

wcscat 749 
wcschr 750 
wcscmp 752 
wcscpy 756 
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SAA functions (continued) 
multibyte (continued) 
wcscspn 758 
wcslen 763 
wcsncat 764 
wcsncmp 766 
wcsncpy 768 
wcspbrk 770 
wcsrchr 772 
wcsspn 776 
wcswcs 788 
program 
abort 47 
atexit 62 
exit 204 
searching 

bsearch 76 
stream input/output 
fclose 212 
feof 222 
ferror 223 
fflush 224 
fgetc 225 
fgetpos 228 
fgets 230 
fprintf 249 
fputc 252 
fputs 255 
fread 261 
freopen 268 
fscanf 271 
fseek 273 
fsetpos 275 
ftell 283 
fwrite 289 
getc 296 
getchar 296 
gets 309 
printf 461 
putc 468 
putchar 468 
puts 473 
scanf 517 
setvbuf 538 
sprintf 554 
sscanf 559 
tmpfile 671 
ungetc 721 
string 

strerror 579 


SAA functions (continued) 
string manipulation 
strcat 565 
strchr 566 
strcmp 567 
strcpy 573 
strcspn 575 
strlen 593 
strncat 595 
strncmp 597 
strncpy 599 
strpbrk 604 
strrchr 610 
strspn 614 
strstr 616 
strtod 621 
strtok 623 
strtol 625 
strtoul 629 
time 

asctime 55 
clock 97 
ctime 129 
difftime 166 
gmtime 321 
localtime 385 
mktime 438 
trigonometric 
acos 51 
asin 57 
atan 61 
atan2 61 
cos 111 
cosh 112 
sin 543 
sinh 544 
tan 645 
tanh 646 

variable argument handling 
va_arg 737 
va_end 737 
va_start 737 
vfprintf 739 
vprintf 741 
vsprintf 743 
scanf function 517 
scanf functions 

infinity and NaN values in 35 
search.h include file 813 
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_searchenv function 523 
searching 

bsearch function 76 
buffers 425 
character keys, for 374 
for file 523 
qsort 478 

strings 566, 604, 614 
strings for tokens 623 
searching and sorting functions 10 
seed 557 

setbuf function 524 

_set_crt_msg_handle function 526 

setjmp function 528 

setjmp.h include file 813 

set 1 ocal e function 530 

_setmode function 535 

setting 

characters 

buffers 432 
characters in strings 603 
file modification time 734 
file translation mode 535 
floating-point control word 109 
settings in child process 549 
setvbuf function 538 
share.h include file 814 
signal function 540 
signal.h include file 814 
signals 

in child process 549 
list of 540 
resetting 541 
signal function 
user-defined 540 
sin function 543 
sine 543 
sinh function 544 
size of allocated memory 441 
size_t 814 
_sopen function 545 
sorting 478 
_spawn functions 
_spawnl 548 
_spawnle 548 
_spawnlp 548 
_spawnlpe 548 
_spawnv 548 
_spawnve 548 
_spawnvp 548 
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_spawn functions (continued) 

_spawnvpe 548 
spawning processes 548 
_splitpath function 552 
sprintf function 554 
square root function 556 
srand function 557 
_srotl function 558 
_srotr function 558 
sscanf function 559 
stack 

stack environment 
restoring 389 
saving 528 
standard streams 
redirecting 

using system function 639 
standard types 
FILE 816 
_stat function 561 
status information, files 561 
status word, floating-point 
clearing 95 
getting 563 
_status87 function 563 
stdarg.h include file 814 
stddef.h include file 814 
stdio.h include file 815 
stdlib.h include file 816 
stopping a program 47 
storage 

allocating 

temporarily 53 

with debug memory functions 139, 145 
with tiled memory functions 647 
checking blocks of 323 
freeing 

getting information about 180, 183, 652, 
699, 702 

reallocating 147, 157, 679 
thread-specific 665 
with debug memory functions 141, 151 
with tiled memory functions 659 
storage allocation 80 
strcat function 565 
strchr function 566 
strcmp function 567 
comparing 

ignoring case 567 



strcmpi function 569 
strcoll function 571 
strcpy function 573 
strcspn function 575 
_strdate function 577 
strdup function 578 
stream I/O functions 15 
stream input/output (I/O) 
fclose 212 
feof 222 
ferror 223 
fflush 224 
fgetc 225 
fgets 230 
fopen 243 
fprintf 249 
fputc 252 
fputs 255 
fread 261 
freopen 268 
fscanf 271 
fseek 273 
ftell 283 
fwrite 289 
getc 296 
getchar 296 
gets 309 
printf 461 
putc 468 
putchar 468 
puts 473 
rewind 497 
scanf 517 
setbuf 524 
setvbuf 538 
sprintf 554 
sscanf 559 
tmpfile 671 
ungetc 721 
va_arg 737 
va_end 737 
va_start 737 
vfprintf 739 
vprintf 741 
vsprintf 743 
streams 

association with file 219 
closing all 213 
standard 

See standard streams 


_strerror function 579, 580 
strfmon function 582 
strftime function 586 
stricmp function 591 
string conversion functions 
_atold 69 
_ecvt 192 
_fcvt 217 
_gcvt 294 

infinity and NaN values in 37 
strtold 627 
string functions 24 
string.h include file 818 
strings 

comparing 569, 575, 591, 597, 601 
concatenating 565, 595 
converting 

from floating point 294 
from integer 368 
from long integer 395 
monetary value to string 582 
multibyte to wide 418, 420 
to floating-point 63, 67 
to formatted time 586 
to integer 65 
to long double 69, 627 
to long integer 67 
to lowercase 594 
to uppercase 631 

wide character to double value 778 
wide character to multibyte 774, 784 
wide character to unsigned long 
value 786 
copying 573 
duplicating 578 
error message 580 
ignoring case 575 
initializing 599, 603 
length of 593 
printing to screen 114 
representing date as 577 
reversing 612 
searching 566, 604, 614 
searching for tokens 623 
setting characters in 603 
strerror 579 
strstr 616 
writing 255 
strlen function 593 
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strlwr function 594 

strncat function 595 

strncmp function 597 

strncpy function 599 

strnicmp function 601 

strnset function 603 

strpbrk function 604 

strptime function 605 

strrchr function 610 

strrev function 612 

strset function 603 

strspn function 614 

strstr function 616 

_strtime function 617 

strtocol 1 function 619 

strtod function 621 

strtok function 623 

strtol function 625 

strtold function 627 

strtoul function 629 

strxfrm function 632 

supported functions 826—848 

suspension of parent process 548 

_swab function 634 

swapping bytes 634 

swpri ntf function 635 

swscanf function 637 

sys\stat.h include file 819 

sys\timeb.h include file 819 

sys\types.h include file 819 

sys\utime.h include file 819 

T 

table of supported functions 826—848 

tan function 645 

tangent 645 

tanh function 646 

_tcalloc function 647 

_d ump_a 11 o c a t ed function 649 

_tdump_al 1 ocated_del ta function 652 

_tell function 655 

_tempnam function 657 

temporary files 

deleting with _fcloseall 213 
names 815 
number of 815 
removing 513 

temporary storage, allocating 53 


terminating 

a process 205 
a program 47, 204 
constructors and destructors 122 
testing 350 

for ASCII alphabetic or underscore 356 
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